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

# Scribe

The Scribe API provides session-centric access to clinical documentation for authenticated providers. Each provider can list sessions they own, retrieve transcripts and coding suggestions, and generate notes, summaries, and checklists.

{% hint style="info" %}
Scribe uses a separate provider-facing API contract that is not published in the Platform API OpenAPI document. The session and artifact pages therefore document those routes manually instead of presenting an invalid Platform embed.
{% endhint %}

## Authentication

All endpoints require a valid provider session token with the `scribe:sessions:read_own` scope. The POST endpoints that generate notes, summaries, or checklists, plus note finalization, also require `scribe:notes:rw_own`; the corresponding GET endpoints do not. The token must belong to a provider principal, and the provider's workspace must match the workspace in the request path. Send the token as a Bearer credential in the `Authorization` header.

## Base Path

All Scribe endpoints are scoped under `/v1/{workspace_id}` and require the workspace identifier as a path parameter. Use the Scribe API base URL supplied for your deployment.

## Resources

| Resource                                                       | Description                                                                                         |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Sessions](/developer-guide/platform-api/scribe/sessions.md)   | List and retrieve clinical documentation sessions owned by the authenticated provider               |
| [Artifacts](/developer-guide/platform-api/scribe/artifacts.md) | Retrieve transcripts and coding suggestions; generate and retrieve notes, summaries, and checklists |

## Error Handling

The Scribe API returns structured error responses with a consistent envelope:

| Field            | Type          | Description                                                                         |
| ---------------- | ------------- | ----------------------------------------------------------------------------------- |
| `code`           | string        | Machine-readable error code (e.g., `not_found`, `validation_error`, `unauthorized`) |
| `message`        | string        | Human-readable error description                                                    |
| `correlation_id` | string (uuid) | Unique identifier for the request, useful for support inquiries                     |
| `details`        | array         | Optional list of field-level validation errors                                      |

Each detail object contains:

| Field     | Type           | Description                             |
| --------- | -------------- | --------------------------------------- |
| `field`   | string or null | The request field that caused the error |
| `message` | string         | Description of the validation failure   |

### Common Error Codes

| HTTP Status | Code                  | Description                                                                                                           |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 401         | `unauthorized`        | Bearer token is absent or invalid                                                                                     |
| 403         | `forbidden`           | The principal lacks a required Scribe scope, provider binding, or workspace access                                    |
| 404         | `not_found`           | No provider-owned resource exists at this URL                                                                         |
| 409         | `conflict`            | Generation cannot proceed because the required transcript is empty or, for checklist generation, is not yet available |
| 422         | `validation_error`    | Request validation failed                                                                                             |
| 503         | `service_unavailable` | The requested Scribe operation is temporarily unavailable                                                             |

## Correlation IDs

Every response includes an `X-Correlation-ID` header. You can also send your own `X-Correlation-ID` header on requests - if valid, the API echoes it back; otherwise a new one is generated. Include the correlation ID when contacting support about a specific request.

## OpenAPI Schema

The Scribe API publishes its OpenAPI schema at the `/v1/openapi.json` endpoint. This schema describes all available endpoints, request and response models, and validation constraints.


---

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