Rewrite Content

Content Rewrite is supported by: Dictation APIs, Web SDK, Dictation SDK

Dictation APIs: You build the rewrite control in your app, call Rewrite content, and put the result back in the field. This page walks through that REST call. It is not part of Dictation WebSocket streaming on /ws/transcribe. For creating a session, streaming audio, and ending a session first, refer to Dictation basic usage.
Web SDK and Dictation SDK: You do not build this UI. Content Rewrite is already in the hosted Dictation iframe, so clinicians select text there, choose Concise, Verbose, or Patient Friendly, and your existing show() callbacks still get the updated field. Refer to Content Rewrite for that flow.

The Rewrite content API lets clinicians rephrase text that is already visible in your application, such as a note, chart field, or scratchpad, without retyping it. Use it when they want that text shorter, more detailed, or easier for a patient to understand. The text can come from a Dictation transcript your application already placed on screen, or from any other plain text your UI manages.

How it works

Select: The clinician highlights text and chooses Concise, Verbose, or Patient Friendly from the rewrite control UI you built.
Call the API: Your app sends that text (selected_text), nearby context (surrounding_content), start and end offsets, and the matching instruction to the Rewrite content API.
Apply the result: The API returns rewritten text and offsets. You replace only the highlighted text and leave the rest of the text in the field as is.

Suki returns text to your application only. It does not write or save content to your EHR.

Common use cases

Content rewrite helps providers shorten long dictation, expand brief wording, or turn clinical terminology into clearer patient-friendly phrasing.

Shorten Long Dictation

The provider selects text and chooses Concise. Call rewrite with CONCISE. The API returns a shorter version that can replace the selected text.

Expand Short Notes

The provider selects short wording and chooses Verbose. Call rewrite with VERBOSE. The API expands the text without adding new facts.

Write for Patients

The provider selects clinical wording and chooses Patient Friendly. Call rewrite with PATIENT_FRIENDLY. The API rewrites jargon in plain language while keeping clinical meaning.

Rewrite After Dictation

After Dictation inserts transcript text into a chart field or scratchpad, let the provider select and rewrite part of the text instead of retyping it or starting another Dictation session.

Rewrite an Ambient Note

When ambient generates a note and the provider needs clearer wording in a section, let them select that span and rewrite it without leaving note review.

Rewrite Text You Already Have

Use the same rewrite call on plain text your application already manages, even when that text did not come from a Dictation session.

Free-form custom instructions are not supported today. The API accepts only CONCISE, VERBOSE, and PATIENT_FRIENDLY. A future release may accept a free-text instruction on the same endpoint.

What you need to build

Your application is responsible for the user experience around content rewrite. You need to build:

Text selection in a chart field, note, or scratchpad
Rewrite control mapped to CONCISE, VERBOSE, or PATIENT_FRIENDLY
Context window and offset logic (up to 5,000 characters each)
Preview or apply step that replaces only the highlighted text
Save path through your existing EHR or application workflow

Prerequisites

Before you start, register the provider and get an sdp_suki_token. Refer to Provider authentication and Partner authentication for more information.

Build the rewrite experience

Add a rewrite control next to editable text in your chart field, note, or scratchpad. Suki rewrites only the text you send in the request. Your app handles selection, calling the API, updating the field, and saving. In practice:

Capture the clinician’s highlighted text and its offsets in the context window you will send.
Map your UI labels (Concise, Verbose, Patient Friendly) to CONCISE, VERBOSE, and PATIENT_FRIENDLY.
On success, replace that highlighted text with the returned content using the returned offsets. Do not auto-write to the EHR.
Let the clinician review, then save through your existing EHR or app workflow.

UI and application responsibilities

UI element	Clinician action	Your application responsibility
Selection	Highlights text to reshape	Capture `selected_text` and Unicode code-point offsets relative to the context window you send
Rewrite control	Chooses Concise, Verbose, or Patient Friendly	Call Rewrite content with the matching `instruction` value
Preview / apply	Reviews and accepts the rewrite	Replace the span using the returned `selection` and `content`. Do not write back automatically
Save	Saves the updated field	Persist the updated content through your existing EHR or application workflow

The workflow is:

Call the Rewrite content API

Content rewrite is a single synchronous REST call after you already have plain text in your UI.

Capture the selected text and a surrounding context window.
Call Rewrite content with one instruction.
Replace the returned span in your UI, then let the clinician review and save.

Call POST Rewrite content API:

Example request

curl --request POST \
  --url https://sdp.suki.ai/api/v1/content/rewrite \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
    "context": {
      "selection": {
        "start": 16,
        "end": 57
      },
      "surrounding_content": "Patient reports mild intermittent headache for three days."
    },
    "instruction": "CONCISE",
    "selected_text": "mild intermittent headache for three days"
  }'

Example response

{
  "content": "mild headache for 3 days",
  "request_id": "trace-123",
  "selection": {
    "start": 16,
    "end": 57
  }
}

The API returns 200 OK when the rewrite succeeds.

Request details

Include sdp_suki_token on every request. For single-auth partners, also send sdp_provider_id. Send the following on every request:

selected_text
instruction
context.selection
context.surrounding_content

Always send context.surrounding_content so the model has enough local context. selected_text must be a subset of that string.

Selection offsets use and represent a , [start, end), relative to surrounding_content.

Request fields

Field	Required	Description
`selected_text`	Yes	Exact text to rewrite. Must be a subset of `surrounding_content`. Length: 1 to 5,000 Unicode code points
`instruction`	Yes	One of `CONCISE`, `VERBOSE`, or `PATIENT_FRIENDLY`
`context.surrounding_content`	Strongly recommended	Context window that includes the selection. Maximum 5,000 Unicode code points. OpenAPI marks this field optional, but send it for a reliable rewrite
`context.selection.start`	Yes	Inclusive start offset in Unicode code points relative to `surrounding_content`
`context.selection.end`	Yes	Exclusive end offset in Unicode code points relative to `surrounding_content`

instruction must be exactly CONCISE, VERBOSE, or PATIENT_FRIENDLY. Do not send lowercase labels such as concise, spaced labels such as patient friendly, or free-form custom instructions. Free-form instructions are not supported.

Rewrites change phrasing, structure, or level of detail. They must not invent, remove, or change clinical facts such as diagnoses, medications, labs, or numbers.

Response details

Field	Description
`content`	Rewritten replacement for `selected_text`
`selection.start` / `selection.end`	Echoed offsets so your UI replaces the correct span
`request_id`	Correlation ID for support

Store request_id with any support ticket about a rewrite result. It helps Technical Support trace the request end to end.

Build the context window

A rewrite request uses two pieces of text from the same field: selected_text, which is the text the clinician selected, and surrounding_content, which is the nearby text the model needs to understand that selection in context. Both can contain up to 5,000 characters. If either field exceeds this limit, the request fails. The selection.start and selection.end offsets must point to the selected text within the surrounding_content you send.

When the field is 5,000 characters or less

If the field is 5,000 characters or less, send the entire field as surrounding_content and set the selection offsets to the position of the highlighted text in that string.

When the field is longer than 5,000 characters

If the field is longer than 5,000 characters, send only a portion that still contains the selection. Include enough text before and after the selection to keep useful context, stay within the limit, and when possible keep the selection near the middle of that portion. Set selection.start and selection.end against the surrounding_content you send, not against the original full field.

When possible, keep the selection near the middle of the context window so the model sees enough text on both sides without sending an oversized payload.

Rewrite workflow

A typical rewrite workflow is:

Authenticate

Obtain an sdp_suki_token for the provider.

Capture the Selection

Let the clinician highlight text in a chart field or note. Capture selected_text, surrounding context, and Unicode selection offsets.

Call Rewrite Content

Call Rewrite content with one instruction: CONCISE, VERBOSE, or PATIENT_FRIENDLY.

Replace the Span

Use the response content and selection to replace the highlighted span in the same context window you sent. Keep the rest of the field unchanged.

Confirm and Save

Keep the original text available until the clinician accepts the rewrite. Then save through your existing EHR or application workflow.

Example code

Rewrite Content API

TypeScript
Python

const response = await fetch("https://sdp.suki.ai/api/v1/content/rewrite", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    sdp_suki_token: sdpSukiToken,
    sdp_provider_id: sdpProviderId,
  },
  body: JSON.stringify({
    context: {
      selection: {
        start: 16,
        end: 57,
      },
      surrounding_content:
        "Patient reports mild intermittent headache for three days.",
    },
    instruction: "CONCISE", // Exact enum values only: CONCISE, VERBOSE, or PATIENT_FRIENDLY.
    selected_text: "mild intermittent headache for three days",
  }),
});

if (!response.ok) {
  throw new Error(`Rewrite content failed: ${response.status}`);
}

const result = await response.json();

// result.content — replacement text
// result.selection — offsets for write-back
// result.request_id — share with Technical Support if needed

import requests

response = requests.post(
    "https://sdp.suki.ai/api/v1/content/rewrite",
    headers={
        "Content-Type": "application/json",
        "sdp_suki_token": sdp_suki_token,
        "sdp_provider_id": sdp_provider_id,
    },
    json={
        "context": {
            "selection": {
                "start": 16,
                "end": 57,
            },
            "surrounding_content": (
                "Patient reports mild intermittent headache for three days."
            ),
        },
        "instruction": "CONCISE",  # Exact enum values only: CONCISE, VERBOSE, or PATIENT_FRIENDLY.
        "selected_text": "mild intermittent headache for three days",
    },
)

response.raise_for_status()

result = response.json()

# result["content"] — replacement text
# result["selection"] — offsets for write-back
# result["request_id"] — share with Technical Support if needed

Handle rewrite failures

Rewrite should not block clinical documentation. If the request fails, keep the original selection on screen and keep chart save available. Match the error id on Ambient and Dictation error messages when you debug.

Status	Error id (examples)	When it happens	What to do
`400`	`invalid_rewrite_content_request`, `provider_user_inactive`, missing or invalid `sdp_provider_id`	Validation failed (instruction, selection offsets, required `context`, or length limits), or the provider user is not active	Fix the request. Show a clear error on the rewrite control only
`401`	`invalid_sdp_token`, `provider_not_registered`	Missing, expired, or invalid Suki Token, or other single-auth identity failure	Refresh authentication, then retry
`403`	`content_rewrite_not_enabled`, `permission_denied`, partner claim failures	Rewrite is not enabled, or the authenticated user cannot access rewrite	Check entitlements with Suki Technical Support. Keep `request_id` when present
`500`	`failed_to_get_enable_content_rewrite_config`, `failed_to_get_user_specialty`	Unexpected server or config error	Retry quietly. Keep `request_id` for support

For step-by-step fixes, refer to Content rewrite returns 400, 403, or 500.

Keep the Original Text

Do not clear or replace the selection if rewrite fails. Leave the clinician on the same field or note.

Keep Save Available

Do not disable EHR or chart save because rewrite failed.

Offer a Quiet Retry

Let the clinician retry from the rewrite control only. Store request_id when you open a support ticket.

Implementation checklist:

Send selected_text, instruction, context.selection, and surrounding_content.
Use the exact instruction values: CONCISE, VERBOSE, or PATIENT_FRIENDLY.
Keep both text fields within 5,000 characters each (selected_text must also be at least 1 character). See invalid_rewrite_content_request.
Preview or confirm before writing the replacement back.
Never block Approve / Save when rewrite fails.

Next steps

Rewrite content - Request fields, limits, and examples. Ambient and Dictation error messages - Rewrite error ids and HTTP mappings. Content rewrite returns 400, 403, or 500 - Fix validation, entitlement, and auth failures. Dictation basic usage - Create a session, stream audio, and end the session before rewrite. Content Rewrite - Hosted iframe flow for Web SDK and Dictation SDK.

Get Started

Concepts & Feature Guides

Executives & Agents

FAQs & Support

Rewrite Content

How it works

Common use cases

Shorten Long Dictation

Expand Short Notes

Write for Patients

Rewrite After Dictation

Rewrite an Ambient Note

Rewrite Text You Already Have

What you need to build

Prerequisites

Build the rewrite experience

UI and application responsibilities

Call the Rewrite content API

Example request

Example response

Request details

Request fields

Response details

Build the context window

When the field is 5,000 characters or less

When the field is longer than 5,000 characters

Rewrite workflow

Example code

Handle rewrite failures

Next steps

​How it works

​Common use cases

Shorten Long Dictation

Expand Short Notes

Write for Patients

Rewrite After Dictation

Rewrite an Ambient Note

Rewrite Text You Already Have

​What you need to build

​Prerequisites

​Build the rewrite experience

​UI and application responsibilities

​Call the Rewrite content API

​Example request

​Example response

​Request details

​Request fields

​Response details

​Build the context window

​When the field is 5,000 characters or less

​When the field is longer than 5,000 characters

​Rewrite workflow

​Example code

​Handle rewrite failures

​Next steps

How it works

Common use cases

What you need to build

Prerequisites

Build the rewrite experience

UI and application responsibilities

Call the Rewrite content API

Example request

Example response

Request details

Request fields

Response details

Build the context window

When the field is 5,000 characters or less

When the field is longer than 5,000 characters

Rewrite workflow

Example code

Handle rewrite failures

Next steps