> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/scribe/sessions.md).

# Sessions

Sessions represent clinical documentation encounters. Each session tracks a lifecycle status and the availability of its transcript, note, summary, and coding artifacts.

{% hint style="info" %}
These provider-facing Scribe routes are absent from the Platform API OpenAPI document. The schemas on this page are manual until the separate Scribe contract is published.
{% endhint %}

## Session Object

| Field                     | Type                      | Description                                                                                            |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `id`                      | string (uuid)             | Unique session identifier                                                                              |
| `status`                  | string                    | Session lifecycle status: `created`, `in-progress`, `in-review`, `completed`, `cancelled`, or `failed` |
| `external_appointment_id` | string or null            | Optional external system appointment identifier (max 512 characters)                                   |
| `started_at`              | string (datetime) or null | When the session started                                                                               |
| `ended_at`                | string (datetime) or null | When the session ended                                                                                 |
| `created_at`              | string (datetime)         | When the session was created                                                                           |
| `updated_at`              | string (datetime)         | When the session was last updated                                                                      |
| `artifacts`               | object                    | Artifact availability summary                                                                          |

### Artifact Availability

The `artifacts` object reports the availability of each artifact type:

| Field        | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `transcript` | string | `pending`, `available`, or `failed` |
| `note`       | string | `pending`, `available`, or `failed` |
| `summary`    | string | `pending`, `available`, or `failed` |
| `codes`      | string | `pending`, `available`, or `failed` |

## List Sessions

```
GET /v1/{workspace_id}/sessions
```

Returns a paginated list of sessions owned by the authenticated provider, ordered by creation time (newest first).

### Query Parameters

| Parameter            | Type    | Default | Description                                                  |
| -------------------- | ------- | ------- | ------------------------------------------------------------ |
| `limit`              | integer | 50      | Number of sessions to return (1-200)                         |
| `continuation_token` | string  | null    | Opaque token from a previous response to fetch the next page |

### Response

| Field                | Type           | Description                                                                                       |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `items`              | array          | List of session objects                                                                           |
| `has_more`           | boolean        | Whether more sessions are available                                                               |
| `continuation_token` | string or null | Token to pass as a query parameter to retrieve the next page. Null when there are no more results |

### Example Request

```bash
curl -H "Authorization: Bearer {token}" \
  "$SCRIBE_API_BASE/v1/{workspace_id}/sessions?limit=10"
```

### Example Response

```json
{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "external_appointment_id": "APT-12345",
      "started_at": "2026-07-15T10:00:00Z",
      "ended_at": "2026-07-15T10:30:00Z",
      "created_at": "2026-07-15T09:55:00Z",
      "updated_at": "2026-07-15T10:31:00Z",
      "artifacts": {
        "transcript": "available",
        "note": "available",
        "summary": "available",
        "codes": "available"
      }
    }
  ],
  "has_more": false,
  "continuation_token": null
}
```

## Get Session

```
GET /v1/{workspace_id}/sessions/{session_id}
```

Returns a single session owned by the authenticated provider.

### Path Parameters

| Parameter      | Type          | Description          |
| -------------- | ------------- | -------------------- |
| `workspace_id` | string (uuid) | Workspace identifier |
| `session_id`   | string (uuid) | Session identifier   |

### Response

Returns a session object (see schema above).

### Errors

| Status | Code        | Description                                                          |
| ------ | ----------- | -------------------------------------------------------------------- |
| 404    | `not_found` | Session does not exist or is not owned by the authenticated provider |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/scribe/sessions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.