> 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/artifacts.md).

# Artifacts

Artifact endpoints return or generate clinical documentation for a session. All routes require the authenticated provider to own the parent session. Read routes require `scribe:sessions:read_own`; generation and finalization also require `scribe:notes:rw_own`.

{% 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 %}

## Get Transcript

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

Returns the transcript for a session, segmented by speaker with timing information.

### Path Parameters

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

### Response

| Field        | Type          | Description                         |
| ------------ | ------------- | ----------------------------------- |
| `session_id` | string (uuid) | Session identifier                  |
| `segments`   | array         | Ordered list of transcript segments |

Each segment contains:

| Field      | Type           | Description                                           |
| ---------- | -------------- | ----------------------------------------------------- |
| `speaker`  | string or null | Speaker label (max 256 characters)                    |
| `text`     | string         | Transcribed text                                      |
| `start_ms` | integer        | Segment start time in milliseconds from session start |
| `end_ms`   | integer        | Segment end time in milliseconds from session start   |

### Example Response

```json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "segments": [
    {
      "speaker": "Provider",
      "text": "How are you feeling today?",
      "start_ms": 0,
      "end_ms": 2500
    },
    {
      "speaker": "Patient",
      "text": "I have been having some back pain.",
      "start_ms": 3000,
      "end_ms": 5500
    }
  ]
}
```

### Errors

| Status | Code                  | Description                                                                      |
| ------ | --------------------- | -------------------------------------------------------------------------------- |
| 404    | `not_found`           | Session not found, not owned by the provider, or transcript is not yet available |
| 503    | `service_unavailable` | Transcript is temporarily unavailable                                            |

## Get Note

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

Returns the clinical note for a session.

### Path Parameters

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

### Response

| Field          | Type                      | Description                              |
| -------------- | ------------------------- | ---------------------------------------- |
| `session_id`   | string (uuid)             | Session identifier                       |
| `type`         | string                    | Note type identifier (max 64 characters) |
| `status`       | string                    | `draft`, `submitted`, or `voided`        |
| `body`         | string                    | Note body text                           |
| `structured`   | object                    | Structured note content                  |
| `generated_at` | string (datetime) or null | When the note was generated              |
| `signed_at`    | string (datetime) or null | When the note was signed                 |
| `updated_at`   | string (datetime)         | When the note was last updated           |

### Example Response

```json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "soap",
  "status": "draft",
  "body": "SUBJECTIVE: Patient reports lower back pain...",
  "structured": {
    "subjective": "Patient reports lower back pain...",
    "objective": "Vitals within normal limits...",
    "assessment": "Lumbar strain",
    "plan": "Physical therapy referral..."
  },
  "generated_at": "2026-07-15T10:31:00Z",
  "signed_at": null,
  "updated_at": "2026-07-15T10:31:00Z"
}
```

### Errors

| Status | Code                  | Description                                                                |
| ------ | --------------------- | -------------------------------------------------------------------------- |
| 404    | `not_found`           | Session not found, not owned by the provider, or note is not yet available |
| 503    | `service_unavailable` | Note is temporarily unavailable                                            |

## Generate a Note

```
POST /v1/{workspace_id}/sessions/{session_id}/note
```

Generates a draft note from the session transcript.

| Request field  | Type           | Default   | Description                                                                                                                                 |
| -------------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `note_type`    | string         | `medical` | One of `full`, `medical`, `soap`, `dap`, `birp`, `amd-psych-intake`, `amd-psych-progress`, `amd-therapy-intake`, or `amd-therapy-progress`. |
| `instructions` | string or null | `null`    | Optional generation guidance, up to 1,200 characters.                                                                                       |

The response contains `note` and `generation`. The generated note starts in `draft` status. A missing transcript returns `404`, an empty transcript returns `409`, and temporary generation failure returns `503`.

## Finalize a Note

```
POST /v1/{workspace_id}/sessions/{session_id}/note/finalize
```

Finalizes the provider-owned note without a request body. The returned note has `submitted` status and a `signed_at` timestamp. A note that is missing or unavailable for finalization returns `404`.

## Session Summary

Use `POST /v1/{workspace_id}/sessions/{session_id}/summary` to generate a concise summary from the session transcript and available note. The response contains `summary` and `generation` objects. Retrieve the latest generated summary with:

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

The summary object contains `session_id`, `summary`, `generated_at`, and `updated_at`.

A missing transcript returns `404`, an empty transcript returns `409`, and a temporary generation failure returns `503`.

## Session Checklist

Use `POST /v1/{workspace_id}/sessions/{session_id}/checklist` to evaluate an explicit checklist against the session transcript.

```json
{
  "title": "Visit checklist",
  "items": [
    { "id": "medications-reviewed", "label": "Medication list reviewed" },
    { "id": "follow-up-planned", "label": "Follow-up plan documented" }
  ]
}
```

Requests accept 1-100 items. Each item ID is 1-128 characters and each label is 1-500 characters. The response includes a checklist with `open` or `checked` item state and optional supporting `evidence`, plus generation metadata.

Checklist generation can use an available partial transcript. It returns `409` when neither a canonical nor partial transcript is available, or when the available transcript is empty. Temporary generation failure returns `503`.

Retrieve the latest checklist with:

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

Checklist status is `open`, `completed`, or `archived`.

## Get Codes

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

Returns ICD code suggestions for a session.

### Path Parameters

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

### Response

| Field        | Type          | Description              |
| ------------ | ------------- | ------------------------ |
| `session_id` | string (uuid) | Session identifier       |
| `items`      | array         | List of code suggestions |

Each code suggestion contains:

| Field         | Type           | Description                                               |
| ------------- | -------------- | --------------------------------------------------------- |
| `code`        | string         | ICD code (max 64 characters)                              |
| `description` | string         | Human-readable description of the code                    |
| `rationale`   | string         | Explanation of why this code was suggested                |
| `confidence`  | number or null | Confidence score between 0 and 1, or null if not computed |
| `status`      | string         | `suggested`, `accepted`, `rejected`, or `voided`          |

### Example Response

```json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "items": [
    {
      "code": "M54.5",
      "description": "Low back pain",
      "rationale": "Patient reported lower back pain during the encounter.",
      "confidence": 0.92,
      "status": "suggested"
    },
    {
      "code": "M54.2",
      "description": "Cervicalgia",
      "rationale": "Patient mentioned occasional neck stiffness.",
      "confidence": 0.65,
      "status": "suggested"
    }
  ]
}
```

### Errors

| Status | Code                  | Description                                                                  |
| ------ | --------------------- | ---------------------------------------------------------------------------- |
| 404    | `not_found`           | Session not found, not owned by the provider, or codes are not yet available |
| 503    | `service_unavailable` | Codes are temporarily unavailable                                            |


---

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