Note generation

Note generation turns a transcript into a clinical note in one synchronous request. It supports a Sully-managed template, an inline template, and structured clinical context. Use this API when the caller can wait for generation to complete and wants the note in the create response.

SDK

Use the SDK’s authenticated request method:

import SullyAI from "@sullyai/sullyai";

type GenerateNoteResponse = {
  requestId: string;
  note: string;
  usage?: { inputTokens: number; outputTokens: number };
};

const client = new SullyAI({
  apiKey: process.env.SULLY_API_KEY,
  accountID: process.env.SULLY_ACCOUNT_ID,
  baseURL: process.env.SULLY_API_BASE_URL,
});

const result = await client.post<GenerateNoteResponse>("/v3/notes", {
  body: {
    transcript:
      "Clinician: What brings you in today? Patient: I have had a dry cough for three days.",
    clinicalContext: {
      patient: {
        name: "Example Patient",
        age: 46,
        gender: "female",
      },
    },
  },
  timeout: 300_000,
  maxRetries: 0,
});

console.log(result.requestId, result.note);

import os

import httpx
from sullyai import SullyAI

client = SullyAI(
    api_key=os.environ["SULLY_API_KEY"],
    account_id=os.environ["SULLY_ACCOUNT_ID"],
    base_url=os.environ["SULLY_API_BASE_URL"],
)

response = client.post(
    "/v3/notes",
    cast_to=httpx.Response,
    body={
        "transcript": (
            "Clinician: What brings you in today? "
            "Patient: I have had a dry cough for three days."
        ),
        "clinicalContext": {
            "patient": {
                "name": "Example Patient",
                "age": 46,
                "gender": "female",
            }
        },
    },
    options={"timeout": 300.0, "max_retries": 0},
)
result = response.json()

print(result["requestId"], result["note"])

Generate a note

curl "$SULLY_API_BASE_URL/v3/notes" \
  --request POST \
  --header "X-Account-Id: $SULLY_ACCOUNT_ID" \
  --header "X-Api-Key: $SULLY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "transcript": "Clinician: What brings you in today? Patient: I have had a dry cough for three days.",
    "clinicalContext": {
      "patient": {
        "name": "Example Patient",
        "age": 46,
        "gender": "female"
      },
      "medications": [
        {"name": "Example medication", "description": "once daily"}
      ],
      "contextItems": [
        {"label": "Visit type", "content": "Outpatient follow-up"}
      ]
    }
  }'

A successful response contains the finished note:

{
  "requestId": "req_...",
  "note": "# History of Present Illness\nThe patient reports a dry cough for three days.\n...",
  "usage": {
    "inputTokens": 1450,
    "outputTokens": 320
  }
}

usage is diagnostic and may be omitted. requestId is also returned in the x-request-id response header; retain it for support.

Choose a template

Omit both template fields to use the default configured experience. To use a Sully-managed template, send templateId:

{
  "transcript": "Fictional encounter transcript...",
  "templateId": "your-template-id"
}

To define the structure in the request, send an inline template:

{
  "transcript": "Fictional encounter transcript...",
  "template": {
    "instructions": "Use concise clinical language and do not infer absent facts.",
    "sections": [
      {
        "title": "History of Present Illness",
        "instructions": "Summarize symptoms, onset, severity, and relevant negatives."
      },
      {
        "title": "Assessment and Plan",
        "instructions": "Separate each assessed problem and its plan."
      }
    ]
  }
}

Do not send templateId and template together.

Request fields

Field	Type	Required	Limits
`transcript`	string	Yes	Nonblank; maximum 100,000 characters.
`templateId`	string	No	Nonblank; maximum 256 characters.
`template.instructions`	string	No	Maximum 10,000 characters.
`template.sections`	array	With inline template	1–50 sections with unique titles.
`template.sections[].title`	string	Yes	Nonblank; maximum 200 characters.
`template.sections[].instructions`	string	Yes	Maximum 10,000 characters.
`clinicalContext.patient`	object	No	Optional `name`, integer `age` from 0–150, and `gender`.
`clinicalContext.medications`	array	No	Up to 100 `{name, description}` items.
`clinicalContext.pastVisits`	array	No	Up to 100 `{date, content}` items.
`clinicalContext.contextItems`	array	No	Up to 100 `{label, content}` items.

The total text in the inline template and clinical context may not exceed 100,000 characters. Unknown fields are rejected so request mistakes fail visibly.

Errors and retries

Errors use a stable code and request ID:

{
  "code": "invalid_request",
  "message": "The request is invalid.",
  "requestId": "req_..."
}

Status	Code	What to do
`400`	`invalid_request`	Correct the body; do not retry unchanged.
`401`	`unauthorized`	Verify the account ID and API key.
`402`	`insufficient_credits`	Add credits before retrying.
`404`	`endpoint_disabled`	Verify that the endpoint is enabled for your account.
`502`	`generation_failed`, `invalid_generation_response`	Retry with backoff if the operation is safe to repeat.
`503`	`generation_unavailable`, `billing_unavailable`	Honor `Retry-After` when present and retry with backoff.
`504`	`generation_timeout`	Retry with backoff if the operation is safe to repeat.

Each POST is a new generation request. If the client disconnects after the request has completed on the server, the response can be lost and a retry can create another billable generation. Use the returned requestId to investigate ambiguous outcomes.

Get started

APIs

SDK

Generate a note

Choose a template

Request fields

Errors and retries

​SDK

​Generate a note

​Choose a template

​Request fields

​Errors and retries

SDK

Generate a note

Choose a template

Request fields

Errors and retries