> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rewrite Content

> Rewrite a selected span of text generated during Dictation or managed within your application with CONCISE, VERBOSE, or PATIENT_FRIENDLY

Use this endpoint to rephrase or rewrite a selected span of text during Dictation or any other text managed within your application.

### Request details

Include the selected text, surrounding content, selection offsets, and one rewrite instruction in the request body.

Use `instruction` to choose how the selection is rewritten:

| Instruction | What it does |
| :- | :- |
| **`CONCISE`** | Shortens the selection while keeping essential details |
| **`VERBOSE`** | Expands terse wording with more clinical detail |
| **`PATIENT_FRIENDLY`** | Rewrites the selection in language that is easier for patients to understand |

<Note>
  * `instruction` must be exactly **`CONCISE`**, **`VERBOSE`**, or **`PATIENT_FRIENDLY`**. Custom free-form instructions are not supported.
  * Keep `selected_text` and `surrounding_content` at **5,000 Unicode code points** or less.
  * `selected_text` must appear inside `surrounding_content`. If the full field is longer, send a shorter window of text around the selection.
</Note>

### Response processing

A successful call returns a `200 OK` status with:

* **`content`**: The rewritten replacement text.
* **`selection`**: Start and end offsets for the span to replace in your UI.
* **`request_id`**: An ID you can share with Technical Support when debugging.

Refer to the [Rewrite Dictation content](/documentation/how-to/dictation/rewrite-dictation-content) guide for implementation details, context window truncation strategies, and write-back guidance.


## OpenAPI

````yaml POST /api/v1/content/rewrite
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, content rewrite, and
    reference metadata endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/content/rewrite:
    post:
      tags:
        - /api/v1/content
      summary: Rewrite selected clinical text
      description: >-
        Rewrites a selected span of clinical text using a server-defined
        instruction (`CONCISE`, `VERBOSE`, or `PATIENT_FRIENDLY`). Send the
        selected text with surrounding context and selection offsets so the
        rewrite preserves meaning. The response returns the rewritten
        replacement text, selection offsets for your UI to apply, and a
        `request_id` for support.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.RewriteContentRequest'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.RewriteContentResponse'
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden. The authenticated user cannot access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            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"
            }'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** for standard partners.


        **Required** for:


        - **Bearer authentication.** Use the same `provider_id` returned by the
        Login or Register API.

        - **Single Auth Token authentication.** Include the same `provider_id`
        on every request as `sdp_provider_id`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.RewriteContentRequest:
      type: object
      description: Request body for POST /api/v1/content/rewrite
      required:
        - context
        - instruction
        - selected_text
      properties:
        context:
          description: Surrounding content and selection offsets for the rewrite.
          allOf:
            - $ref: '#/components/schemas/controllers.RewriteContext'
        instruction:
          description: >-
            Server-defined rewrite instruction. Must be exactly one of
            `CONCISE`, `VERBOSE`, or `PATIENT_FRIENDLY`.
          type: string
          enum:
            - CONCISE
            - VERBOSE
            - PATIENT_FRIENDLY
          example: CONCISE
        selected_text:
          description: >-
            Text span to rewrite. Must be a subset of
            `context.surrounding_content` when surrounding content is provided.
            Length must be 1 to 5000 Unicode code points.
          type: string
          minLength: 1
          maxLength: 5000
          example: mild intermittent headache for three days
      example:
        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
    controllers.RewriteContentResponse:
      type: object
      description: Response body for POST /api/v1/content/rewrite
      properties:
        content:
          type: string
          description: Rewritten replacement for `selected_text`.
          example: mild headache for 3 days
        request_id:
          type: string
          description: >-
            Server-assigned correlation ID. Share this with Technical Support
            when debugging a rewrite request.
          example: trace-123
        selection:
          description: >-
            Echo of the request selection offsets when provided. Use these
            offsets to replace the span in your UI.
          allOf:
            - $ref: '#/components/schemas/controllers.RewriteSelection'
      example:
        content: mild headache for 3 days
        request_id: trace-123
        selection:
          start: 16
          end: 57
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.RewriteContext:
      type: object
      description: Surrounding content plus selection offsets for a rewrite request.
      required:
        - selection
      properties:
        selection:
          $ref: '#/components/schemas/controllers.RewriteSelection'
        surrounding_content:
          type: string
          description: >-
            Surrounding text that includes the selection. Maximum 5000 Unicode
            code points. Provide enough context before and after the selection
            so the rewrite preserves meaning.
          maxLength: 5000
          example: Patient reports mild intermittent headache for three days.
    controllers.RewriteSelection:
      type: object
      description: >-
        Half-open `[start, end)` range in Unicode code points identifying the
        span of `surrounding_content` to rewrite.
      properties:
        start:
          type: integer
          description: >-
            Inclusive start offset in Unicode code points relative to
            `surrounding_content`.
          example: 16
        end:
          type: integer
          description: >-
            Exclusive end offset in Unicode code points relative to
            `surrounding_content`.
          example: 57
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.