> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore a deleted session

> Takes a session out of the recycle bin; it and its notes are visible again. A session that is not in the bin is left as it is (`changed: false`). Returns 404 if the session isn't your organization's. Requires notes:write.

| Requirement | Detail |
| - | - |
| **Scope** | `notes:write` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!NOTE]
>
> **Safety**
>
> * **Writes data:** Yes. Takes the session out of the recycle bin.
> * **Safe to retry:** Yes. A session that is not in the bin is left as it is (`changed: false`).
> * **Contacts an outside system:** None
> * **Dry run:** Not available.

> [!NOTE]
>
> Rolling out: this endpoint is on staging first and not yet on `api.healos.ai`.

The session returns as `completed` when its transcript finished, otherwise `finalizing`. Another organization's session is a `404`.

Guide: [Making requests](https://docs.healos.ai/making-requests.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json POST /sessions/{sessionId}/restore
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /sessions/{sessionId}/restore:
    post:
      tags:
        - Notes
      summary: Restore a deleted session
      description: >-
        Takes a session out of the recycle bin; it and its notes are visible
        again. A session that is not in the bin is left as it is (`changed:
        false`). Returns 404 if the session isn't your organization's. Requires
        notes:write.
      parameters:
        - schema:
            type: string
            description: Session UUID
            example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          required: true
          name: sessionId
          in: path
      responses:
        '200':
          description: The session is restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionTrashResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs notes:write)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    SessionTrashResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            session_id:
              type: string
            status:
              type: string
              description: >-
                The session status now: `deleted` after a delete; `completed` or
                `finalizing` after a restore.
              example: deleted
            changed:
              type: boolean
              description: >-
                False when the session was already in that state (a repeat
                delete, for example). Nothing was changed.
          required:
            - session_id
            - status
            - changed
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.