> ## 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.

# Delete a session

> Moves the session and its notes to the recycle bin, the same as deleting a visit in the dashboard. It can be restored with POST /sessions/{sessionId}/restore. This never deletes permanently: a session already in the bin is left as it is (`changed: false`). Emptying the bin stays in the dashboard. 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 |

> [!WARNING]
>
> **Safety**
>
> * **Writes data:** Yes. Moves the session and its notes to the recycle bin. It is **not** a permanent delete: restore it with [Restore a deleted session](https://docs.healos.ai/api-reference/sessions/restore-a-deleted-session.md). Emptying the recycle bin is only possible in the dashboard.
> * **Safe to retry:** Yes. A repeat finds the session already in the bin, changes nothing and returns `changed: false`.
> * **Contacts an outside system:** None. Notes already sent to an EHR stay there.
> * **Dry run:** Not available.

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

A deleted session no longer appears in `GET /sessions/{sessionId}` or the notes endpoints. 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 DELETE /sessions/{sessionId}
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}:
    delete:
      tags:
        - Notes
      summary: Delete a session
      description: >-
        Moves the session and its notes to the recycle bin, the same as deleting
        a visit in the dashboard. It can be restored with POST
        /sessions/{sessionId}/restore. This never deletes permanently: a session
        already in the bin is left as it is (`changed: false`). Emptying the bin
        stays in the dashboard. 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 in the recycle bin
          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.