Skip to main content
Beta
The /documents/sections endpoints — including section versions and publish — are available in beta. Feedback welcome at help@corti.ai or via your Corti contact.

​
What is a section?

A section is a reusable, versioned building block for document generation. It defines a single piece of structured output — for example a Clinical Findings section or an Allergies section — with its own:
  • heading — a heading passed to the LLM and used in rendered output.
  • instructions — the prompts that drive content selection, writing style and any miscellaneous guidance.
  • outputSchema — the shape of the output (string, number, boolean, array or object). The schema is also a prompting surface: descriptions, enums, patterns, formats and min/max constraints all flow into how the LLM generates the content.
Sections are first-class resources. You can list, version, publish and reuse them across many templates.

​
When to author your own sections

ScenarioWhy a custom section
You want a section that doesn’t exist in the Corti standard library (e.g., a specialty-specific field)Author once, reuse everywhere
You want stable, versioned control over the prompt for a section your customers rely onVersion & publish lifecycle
You want a structured output (object/array with fields) instead of free-textoutputSchema lets you constrain shape
You want to fine-tune a Corti default section while still inheriting future improvementsUse inheritFromId — see Inheritance

​
Section lifecycle at a glance

1

Create the section

POST /documents/sections creates the section resource and its version 0. By default the new version is automatically published. Set publish: false to prevent the new section being returned in LIST /documents/sections
2

Iterate with new versions

POST /documents/sections/{sectionID}/versions creates a new version with a fresh generation config. New versions are not automatically published — the previously published version stays live until you explicitly publish a new one.
3

Publish a version

POST /documents/sections/{sectionID}/versions/{versionID}/publish sets that version as the published version. Only the published version is referenced by templates and used at generation time.
4

Use in a template or generation request

Reference the section by id from a template, or compose sections directly in a POST /documents request. See Create a Template.
A section must be published before it can be referenced by a published template version or used in generation. publish: true is the default on creation.

​
Create your first section

​
Minimal request — string output

The simplest section produces a free-text string. You only need name and a generation block with heading, instructions.contentPrompt and an outputSchema of type: string. Optionally add languages, regions, specialties and labels if you want the section to be discoverable by those filters. 
// Replace these with your values
const ACCESS_TOKEN = "<your-access-token>";

const section = await client.documents.sections.create({
  name: "Clinical Findings",
  languages: ["en"],
  description: "Summarises the key clinical findings from the interaction.",
  labels: [{ key: "category", value: "clinical" }],
  generation: {
    heading: "Clinical Findings",
    instructions: {
      contentPrompt: "Extract all relevant clinical findings mentioned during the interaction.",
      writingStylePrompt: "Use concise, professional medical language.",
    },
    outputSchema: { type: "string" },
  },
});
The response is the created section, including its auto-published version 0:
Section response
{
  "id": "<your-section-id>",
  "source": "user",
  "name": "Clinical Findings",
  "languages": ["en"],
  "regions": [],
  "specialties": [],
  "description": "Summarises the key clinical findings from the interaction.",
  "labels": [{ "key": "category", "value": "clinical" }],
  "publishedVersion": {
    "id": "<your-version-id>",
    "versionNumber": 0,
    "generation": {
      "heading": "Clinical Findings",
      "instructions": {
        "contentPrompt": "Extract all relevant clinical findings mentioned during the interaction.",
        "writingStylePrompt": "Use concise, professional medical language."
      },
      "outputSchema": { "type": "string" }
    }
  },
  "createdAt": "2026-05-12T10:00:00Z",
  "updatedAt": "2026-05-12T10:00:00Z"
}
Keep the name and description human-friendly — they are not passed to the LLM. The heading and instructions are what the model sees.

​
Configuring the generation block

​
instructions

FieldPurpose
contentPrompt (required)What the section should include. In documentationMode: routed_parallel, this also drives which facts get routed to this section.
writingStylePromptTone, register and style (e.g. telegraphic, lay-person, formal narrative).
miscPromptFree-form prompt for anything that doesn’t fit content or style — e.g. formatting nuances, fixed disclaimers, edge-case handling.

​
outputSchema

outputSchema declares the shape and also acts as an additional prompting surface. The discriminator is type:
  • string — free text, optionally constrained by default, enum, or pattern.
  • number — integer or float, optionally constrained by enum, minimum, maximum, default.
  • boolean — true/false, with an optional default.
  • array — list of items of any schema type; configure itemFormat (a format string that must contain the {item} placeholder, e.g. "- {item}\n"), and minItems/maxItems.
  • object — multi-field structured output. Declare fields[] (each with its own key, description, value schema). Control rendering with fieldFormat — either as a per-field iteration template using generic {key} / {value} placeholders (e.g. "{key}: {value}\n" inline, "{key}\n{value}\n" block) or as a fully custom layout referencing specific field keys (e.g. "{test}: {result}").
The description on a schema node is a prompting field too — use it to give the model targeted guidance that supplements instructions.

Designing Section Output Schemas — full reference

The summary above is just the shape. For required-vs-optional fields per node type, the regex/enum/default behavior on string, the itemFormat and fieldFormat rendering primitives (both per-field iteration and fully custom layouts), and copy-paste clinical examples (fixed subheadings with explicit defaults, dynamic organ-system labels, mixed-type test results, EHR placeholders, prefixes like Rp.), see the Section Schemas guide.

​
Example — structured object output

A Vital Signs section that returns a structured object with consistent rendering:
Section with object outputSchema
{
  "name": "Vital Signs",
  "languages": ["en"],
  "labels": [
    { "key": "category", "value": "clinical" },
    { "key": "category", "value": "exam" }
  ],
  "generation": {
    "heading": "Vitals",
    "instructions": {
      "contentPrompt": "Extract vitals discussed during the encounter: blood pressure, heart rate, respiratory rate, temperature and SpO2. Omit any that were not mentioned.",
      "writingStylePrompt": "Telegraphic — values only, no narrative."
    },
    "outputSchema": {
      "type": "object",
      "fieldFormat": "**{key}**: {value}",
      "fields": [
        { "key": "Blood pressure", "description": "Systolic/diastolic in mmHg.", "value": { "type": "string", "pattern": "^\\d{2,3}/\\d{2,3}$" } },
        { "key": "Heart rate", "description": "Beats per minute.", "value": { "type": "number", "minimum": 0, "maximum": 300 } },
        { "key": "Respiratory rate", "description": "Breaths per minute.", "value": { "type": "number", "minimum": 0, "maximum": 80 } },
        { "key": "Temperature", "description": "In °C.", "value": { "type": "number" } },
        { "key": "SpO2", "description": "Percent oxygen saturation.", "value": { "type": "number", "minimum": 0, "maximum": 100 } }
      ]
    }
  }
}

​
Example — array of items

A Diagnoses section returning a numbered list, capped at five items:
Section with array outputSchema
{
  "name": "Diagnoses",
  "languages": ["en"],
  "generation": {
    "heading": "Diagnoses",
    "instructions": {
      "contentPrompt": "List the diagnoses discussed or established during the encounter, most relevant first."
    },
    "outputSchema": {
      "type": "array",
      "itemFormat": "* {item}\n",
      "minItems": 0,
      "maxItems": 5,
      "items": { "type": "string" }
    }
  }
}

​
Next steps

Inheritance

Create inheriting variants of this section to scale across customers, departments and specialties.

Versioning & publishing

Iterate by creating new versions and publishing them on your own cadence.

Manage & discover

Read resolved-vs-raw, update metadata, delete with inheritance guards, filter LIST results.

Create a Template

Compose your sections into a versioned template that can be referenced at generation time.