> 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/artifacts.md). # Artifacts Retrieve Scribe transcripts, follow asynchronous artifact generation, review visit checklists, and finalize clinical notes with version checks. Artifacts belong to a provider-owned [Scribe session](/developer-guide/platform-api/scribe/sessions.md). Every route below checks that the authenticated provider owns the session and requires `scribe:sessions:read_own`. Generation, note edits, checklist changes, and note finalization also require `scribe:notes:rw_own`. Use your assigned [Scribe deployment and credentials](/developer-guide/platform-api/scribe.md). For the full capture and review workflow, see [Capture to Finalized Note](/developer-guide/guides/scribe-capture-to-note.md). ## Get Transcript {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/transcript" method="get" %} {% endopenapi %} `workspace_id` and `session_id` are UUIDs. The response contains `session_id` and an ordered `segments` array. Each segment has `text`, a nullable `speaker`, and integer `start_ms` and `end_ms` offsets from session start. ```json { "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "segments": [ { "speaker": "Provider", "text": "How are you feeling today?", "start_ms": 0, "end_ms": 2500 } ] } ``` A missing or inaccessible session, or an unavailable transcript, returns `404`. Temporary transcript retrieval failures return `503`. ## Get Note {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/note" method="get" %} {% endopenapi %} Read `generation_status` before displaying the note: | Value | Meaning | Client behavior | | --------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | | `pending` | Generation has not completed | Continue checking this endpoint; artifact fields can be null. | | `ready` | The note is available | Display `structured` and retain `version` for subsequent edits or finalization. | | `failed` | Generation failed | Show the failure state and use any returned error details. | | `empty` | The session ended without usable transcript segments | Show that no note was generated; stop waiting for this generation. | When ready, the response includes `session_id`, `type`, `status`, `structured`, `version`, and generation, signing, and update timestamps. `body` is deprecated. The note's document `status` (`draft`, `submitted`, or `voided`) is separate from its `generation_status`. ### EHR Writeback Fields Every note read includes `writeback_status`, which reports whether the note has been written back to a configured EHR: | Value | Meaning | | --------------- | ---------------------------------------------------------------------------------------------------------------------- | | `succeeded` | The note was written back when it was finalized. | | `pending` | EHR writeback is enabled for the workspace and the note has not been finalized yet. | | `disabled` | EHR writeback is not enabled for the workspace. The note will not be written back. | | `not_attempted` | Writeback is enabled, but the note was finalized (or ended with no note) without a writeback. It is not retried later. | Check `writeback_status == "succeeded"` when you only need to know whether the note reached the EHR. The other values separate workspace configuration from note history. When EHR writeback is enabled and the session is linked to an EHR appointment with a supported note template, a ready note can also include: * `carry_forward_available`: the fields that have a value available to carry forward from the patient's last signed note. Each entry names the field code, an optional label, the carried display `value`, and the source note's identifier and signed date when the EHR attributes one. `value` is `null` when the EHR attributes no display value to the field. Treat `value` as chart content and handle it like the note body. Use these entries to show the provider what the EHR would carry while they edit the note. * `clinician_name`: the authoring clinician's display name as the EHR reports it. Treat it as display context, not as a readiness or writeback signal. Both are best-effort. `carry_forward_available` is an empty list and `clinician_name` is `null` when writeback is disabled, the note is not linked to a supported EHR appointment, or the EHR lookup fails. A failed lookup does not fail the note read. A session with no note-generation record returns `404`; an artifact that is temporarily unavailable returns `503`. Do not interpret every non-ready response as a missing session. ## Generate a Note {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/note" method="post" %} {% endopenapi %} Generation requires a mutable session and an available, non-empty canonical transcript. A missing transcript returns `404`; an empty transcript returns `409`. | Request field | Contract | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `note_type` | Optional compatibility selector; may be null. Accepts only the current note template identifiers. The session's pinned note template takes precedence. | | `instructions` | Optional generation guidance, up to 1,200 characters; may be null. | Use the [visit type and template selected on the session](/developer-guide/platform-api/scribe/sessions.md#create-an-in-person-session) to establish the note format. Changing this request's `note_type` does not override a pinned session template. A new or pending generation returns `202` with a generation envelope. If an identical generation has already succeeded, the route can return `200` with `note` and `generation`. Poll **Get Note** for the current result. A successful enqueue does not mean a draft is ready to display. ## Save an Edited Note {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/note" method="put" %} {% endopenapi %} Read the current note, retain its `version`, and send that value as `base_version` with the complete `structured` document. This is a full document replacement, not a field patch. Preserve unchanged values and the pinned template; an autosave cannot switch templates. A successful save returns the new version and update time. Use that version for the next edit or finalization. A stale version returns `409 version_conflict`: reload and reconcile the provider’s edits before saving again. A terminal session rejects edits. A missing note returns `404`, and an invalid or incompatible structured document returns `422` with validation details. Use `structured` for all note edits. The note-update request does not accept a `body` field; regenerate a client, or upgrade an SDK, that offers a body-only edit. The deprecated `body` field on a note **response** is a separate compatibility field and is always null. ## Regenerate One Section {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/note/regenerate-section" method="post" %} {% endopenapi %} Regeneration uses the requested section, optional instructions, and the reviewed `base_version`. It is asynchronous: acceptance does not mean the revised note is ready. Version checks apply both when the request is accepted and when the result is saved, so concurrent edits can prevent the generated section from replacing a newer note. Read the resulting note and have the provider review it before finalizing. ## Finalize a Note {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/note/finalize" method="post" %} {% endopenapi %} Finalization requires a JSON body containing the positive integer `base_version` of the note the provider reviewed. Read that version from **Get Note**; the value below is illustrative. ```json { "base_version": 3 } ``` On success, the response wraps the submitted note in `note` and includes the note's [`writeback_status`](#ehr-writeback-fields). Submission sets `signed_at` and completes the session atomically. An already submitted note is an idempotent success. When EHR writeback is enabled for the workspace, finalization writes the note to the EHR as part of the same operation. If the writeback fails, the whole finalize is rolled back: the note stays a draft, the session is not completed, and the route returns `ehr_writeback_failed` with a `reason` entry in `details`: | Status | Reasons | What to do | | ------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `500` | `provider_email_missing`, `appointment_link_missing`, `unsupported_note` | The note could not be prepared for the EHR. Fix the provider account, appointment link, or note template before retrying. | | `502` | `ehr_rejected`, `ehr_unavailable`, `chart_note_failed`, `chart_note_not_written` | The EHR call failed. An `ehr_message` entry can carry the EHR's own error text. Retry after the cause clears, using the current `base_version`. | Because nothing was committed, a retry can succeed without reloading, unless the note changed in the meantime. The finalize response also includes `field_dispositions`, a per-field summary of how the writeback handled each known field of the note template. Each entry carries the field code, an optional label, a `disposition` of `written` or `omitted`, a `reason`, and an optional `source`: | `reason` | Meaning | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `written_from_transcript` | Written from the note drafted from the visit transcript. | | `written_from_clinician_edit` | Written because the provider edited this field. The edit is sent even when the EHR has a value to carry forward. | | `written_session_meta` | Written from per-visit session details, such as times and dates of service. | | `omitted_carried_forward` | Not sent because the provider did not edit the field and the EHR carries the value forward from a prior signed note. | | `omitted_identity_autowritten` | Not sent because the EHR writes this identity field itself. | | `omitted_empty_no_value` | Not sent because the carried-forward field had no value. | | `not_populated` | A known template field that this writeback did not fill. | A field the provider edits takes precedence over a carried value: it is written with `source` set to `clinician_edit`. A field the provider leaves untouched steps aside so the EHR carries its prior value. Carried-forward entries name the source note in `source_note_id`, `source_signed_at`, and `source_template_name`. Carried-forward and EHR identity entries include the value the EHR uses in `display_value`. Written and not-populated entries leave it out, because written values are already in the note. Treat `display_value` as chart content and handle it like the note body. The array is empty when EHR writeback is not enabled, and on an idempotent re-finalize of an already submitted note. For an unsubmitted note, a stale version returns `409 version_conflict`: reload the current note and have the provider review it before trying again. A missing note returns `404`; a cancelled or failed session returns `409 invalid_session_state`. Finalization checks the version but can submit a note with missing clinical fields. The provider must review its completeness and correctness before submission. ## Session Summary {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/summary" method="post" %} {% endopenapi %} {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/summary" method="get" %} {% endopenapi %} The POST generates a summary from the session transcript and available note. It requires a mutable session and a non-empty transcript. Like note generation, it returns `202` while work is pending or `200` with `summary` and `generation` when an identical completed result can be reused. The GET returns `generation_status` (`ready`, `pending`, or `failed`). When ready, it also returns the summary text, `session_id`, `generated_at`, and `updated_at`; those artifact fields may be null while pending or failed. No generation record returns `404`. ## Session Checklist A session's visit type supplies its checklist. Clients read and update those existing items; they do not submit an arbitrary checklist for generation. {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/checklist" method="get" %} {% endopenapi %} A checklist can be available before a transcript exists. A successful read includes `generation_status: "ready"`, the checklist title and status, and items with `id`, `label`, `category`, `state`, and optional evidence and provenance. Effective item state is `open` or `checked`. A session with no checklist returns `404`. {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/checklist" method="patch" %} {% endopenapi %} Submit 1-100 toggles using IDs returned by the GET. `completed` is required; `source`, when supplied, must be `manual`. ```json { "items": [ { "id": "medications-reviewed", "completed": true, "source": "manual" } ] } ``` The example ID must be replaced with one from the session's checklist. The response is the effective checklist, with item provenance and a recomputed status. An unknown item ID returns `422`, a missing checklist returns `404`, and a terminal session returns `409 invalid_session_state`. {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/checklist/auto-check" method="post" %} {% endopenapi %} Auto-check evaluates the checklist against the available canonical or partial transcript and returns per-item matches. It preserves manually decided items. If there is no checklist or usable transcript, the response can contain an empty `matches` array; that does not mean the checklist has been satisfied. ## Get Codes {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/codes" method="get" %} {% endopenapi %} Returns the session's code suggestions and provider-authored codes in `items`. Each item includes `id`, `code`, `description`, `rationale`, an optional `confidence`, a `decision`, and a `source`. Treat these items as the current code list even while AI generation is pending or failed. `generation_status` describes AI generation separately: `ready` when none has run or it has succeeded, `pending` while running, or `failed` with error information. An empty code list is valid. `decision` is null until the provider decides, then `approved` or `rejected`. `source` is `ai` for a generated suggestion or `provider` for a code the provider added. A confidence value is not an approval. {% openapi src="" path="/v1/{workspace\_id}/sessions/{session\_id}/codes" method="post" %} {% endopenapi %} Explicit code generation requires a mutable session and a non-empty transcript. It follows the same `202` pending or `200` reused-result pattern as summary generation. Read the GET endpoint for the current code list and generation state. --- # 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/artifacts.md?ask=&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.