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

# Scribe

Access provider-owned clinical documentation sessions, retrieve transcripts, generate notes and summaries, and review visit checklists and coding suggestions.

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, generate notes and summaries, and review the checklist supplied by the session's visit type.

{% hint style="info" %}
Scribe has its own public OpenAPI schema and provider access boundary. Use the [Scribe HTTP Reference](https://docs.concurrence.com/api-reference/readme/scribe) for canonical operation contracts and [Capture to Finalized Note](/developer-guide/guides/scribe-capture-to-note.md) for the complete workflow. Use the Scribe deployment base assigned to your integration, separately from Platform text sessions.
{% endhint %}

## TypeScript SDK

Use [`@concurrence-hq/scribe-typescript-sdk`](https://www.npmjs.com/package/@concurrence-hq/scribe-typescript-sdk) 1.4.0 or later for Scribe REST helpers, streaming, and browser recording. Versions before 1.0.0 do not send the required session `timezone`, so their session creates fail with `422`. Version 1.5.0 also types the carried `value` on `carry_forward_available` entries and the clinician-edit field dispositions that the service returns. The package is ESM-only and supports Node.js 20+ and browsers with the required capture APIs. Its [integration guide](https://github.com/concurrence-hq/scribe-typescript-sdk/blob/main/docs/customer-integration.md) explains the exported `ScribeRecorder`, separately provisioned provider access, and the backend route that obtains browser attach tickets. Keep provider credentials on your backend and enforce application access to the requested appointment or session.

```bash
npm i @concurrence-hq/scribe-typescript-sdk
```

```ts
import { ScribeClient, ScribeServerClient, ScribeStreamClient, ScribeRecorder } from '@concurrence-hq/scribe-typescript-sdk'
```

{% hint style="warning" %}
`@amigo-ai/scribe-typescript-sdk` (0.15.1) is deprecated and receives no updates; installs pinned to it keep working. Install `@concurrence-hq/scribe-typescript-sdk` and change the import path. Version 0.16.0 has the same API as 0.15.1; 1.0.0 and later require `timezone` on session create and accept only the current visit types and note templates.
{% endhint %}

## Authentication

Read operations require a valid provider token with `scribe:sessions:read_own`. Session creation, updates, lifecycle transitions, and Zoom controls require `scribe:sessions:write`. Artifact generation and finalization use their documented note-write scopes. Check the owning route rather than treating one scope as sufficient for every operation. 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)   | Create, inspect, and manage provider-owned clinical sessions, including Zoom capture                           |
| [Artifacts](/developer-guide/platform-api/scribe/artifacts.md) | Retrieve transcripts and codes, follow note and summary generation, review checklist items, and finalize notes |

## 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         | Route-specific, such as `conflict`, `version_conflict`, or `invalid_session_state` | An empty transcript, a stale note version, or the session lifecycle prevents the requested operation |
| 422         | `validation_error`                                                                 | Request validation failed                                                                            |
| 503         | `service_unavailable`                                                              | The requested Scribe operation is temporarily unavailable                                            |

### Temporary Maintenance and Reconnection

During maintenance, ordinary Scribe HTTP requests can return `503` with `Retry-After`. Honor the returned delay. Newly attaching streams can close with WebSocket code `1013` (try again later); an already attached stream is not terminated by this maintenance gate. Do not assume the installed SDK automatically retries every close code. Preserve the session ID, surface the interrupted state, and retry connection setup through the supported allocation and ticket flow after recovery.

Before repeating a note edit or finalization after an uncertain response, read the current note and version. A maintenance or transport error is not evidence that capture, generation, or a previous write completed.

## 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/scribe.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.