Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.corti.ai/llms.txt

Use this file to discover all available pages before exploring further.

Beta. The /documents/templates endpoints — including template versions and publish — are available in beta. Feedback welcome at help@corti.ai or via your Corti contact.

​
What is a template?

A template combines one or more published sections with a top-level instruction and exposes a single, versioned resource that can be referenced at generation time. Where a section is the building block, a template is the assembled note: e.g. a Post-Consultation Note template made up of Chief Complaint, History of Present Illness, Assessment, and Plan sections. A template has:
  • Metadata — name, description, language, labels. Metadata is not passed to the LLM.
  • instructions.prompt — a template-level prompt that applies to all sections during generation (e.g. setting overall tone, framing the encounter, or referencing the audience for the note).
  • sections[] — references to existing sections by sectionId, plus an orderIndex controlling the order they appear in the generated document.
Templates, like sections, are versioned and publishable. Only the published version is used at generation time.

​
Prerequisites

You will need:
  1. At least one published section. See Create a Section.
  2. The section’s id (UUID). You can obtain this from the create response or by listing sections via GET /documents/sections.
Only published sections can be referenced in a published template version. If you reference an unpublished section, the template version will fail to publish until that section is published.

​
Template lifecycle

1

Create the template

POST /documents/templates creates the template resource and its version 0. By default the new version is automatically published (publish: true).
2

Iterate with new versions

POST /documents/templates/{templateID}/versions creates a new version with a fresh generation block. New versions are not automatically published.
3

Publish a version

POST /documents/templates/{templateID}/versions/{versionID}/publish sets that version as the published version of the template.
4

Use the template at generation time

Reference the template by id from a document-generation request.

​
Create your first template

The template below references two sections you’ve already published. orderIndex starts at 0 and controls section order in the output. 
// Replace these with your values — section IDs come from LIST /documents/sections
const SECTION_ID_1 = "<your-section-id>";
const SECTION_ID_2 = "<your-section-id>";

const template = await client.documents.templates.create({
  name: "Post-Consultation Note",
  languages: ["en"],
  description: "Standard note produced after a patient consultation.",
  labels: [{ key: "category", value: "consultation" }],
  generation: {
    instructions: {
      prompt: "Produce a structured clinical note from the consultation. Refer to the patient by their pronouns when known.",
    },
    sections: [
      { sectionId: SECTION_ID_1, orderIndex: 0 },
      { sectionId: SECTION_ID_2, orderIndex: 1 },
    ],
  },
});
The response is the created template with the auto-published version 0. On GET /documents/templates/{templateID} the response is resolved — each referenced section is fully expanded with all inheritance applied, ready to be consumed as-is. The version reads (GET /documents/templates/{templateID}/versions/{versionID} and LIST /documents/templates/{templateID}/versions) return the raw template version — only the values the template itself owns, plus the section references. Use the version reads when you need to distinguish inherited fields from fields this template explicitly overrides.
Template response
{
  "id": "<your-template-id>",
  "source": "user",
  "name": "Post-Consultation Note",
  "languages": ["en"],
  "regions": [],
  "specialties": [],
  "description": "Standard note produced after a patient consultation.",
  "labels": [{ "key": "category", "value": "consultation" }],
  "publishedVersion": {
    "id": "<your-version-id>",
    "versionNumber": 0,
    "generation": {
      "instructions": {
        "prompt": "Produce a structured clinical note from the consultation. Refer to the patient by their pronouns when known."
      },
      "sections": [
        { "id": "<your-section-id>", "name": "Chief Complaint", "...": "..." },
        { "id": "<your-section-id>", "name": "History of Present Illness", "...": "..." }
      ]
    }
  },
  "createdAt": "2026-05-12T10:00:00Z",
  "updatedAt": "2026-05-12T10:00:00Z"
}

​
How template instructions interact with section instructions

A template’s generation.instructions.prompt is applied at the top level, alongside each section’s own instructions. Use it for cross-section guidance that you don’t want to repeat in every section:
  • Overall persona, audience or register (e.g. “Write for a referring specialist”).
  • Encounter framing (e.g. “This is a follow-up visit, not a new consultation”).
  • Patient or scenario context that all sections should respect.
Keep section-specific guidance in the section. Keep template-wide guidance in the template prompt. Mixing them makes templates harder to reuse — and harder for the LLM to disambiguate when instructions conflict.

​
Inheriting from an existing template

You can create a template that inherits from another template’s published version. Fields you omit in generation are inherited; fields you provide override.
Inherit & override
{
  "name": "Post-Consultation Note (Pediatrics)",
  "languages": ["en"],
  "inheritFromId": "<your-template-id>",
  "generation": {
    "instructions": {
      "prompt": "Produce a pediatric consultation note. Refer to the patient as 'the child'."
    }
  }
}
If you omit sections from generation, the inherited template’s section composition is kept as-is. Provide a sections array if you want to replace the section composition entirely.
Inheritance resolves against the published version of the referenced template at request time. Future improvements to the upstream template propagate to fields you have not overridden.
Inheriting from a Corti Standard — silent updates. Corti improves and refines its Corti Standard templates continuously. Updates are typically silent — small prompt refinements and quality fixes ship the same way many small API releases do, without per-change notes. Only clear schema-breaking changes or significant behavior changes are explicitly communicated.Inheritance cannot pin you to a specific upstream version. If your integration requires staying on a specific behavior, do not use inheritFromId against a Corti Standard — instead, re-create the template as your own resource by copying its configuration into a POST /documents/templates request without inheritFromId. The new resource is yours to version; subsequent Corti updates will not reach it.This caveat applies specifically to inheritance from Corti Standards. When inheriting from templates you yourself authored, your project controls the publish cadence — there are no silent updates from Corti to worry about.

​
Versioning a template

Once a template exists, iterate by creating new versions. The published version stays live until you explicitly publish a new one. 
// Replace these with your values
const SECTION_ID_1 = "<your-section-id>";
const SECTION_ID_2 = "<your-section-id>";
const SECTION_ID_NEW = "<your-section-id>";
const TEMPLATE_ID = "<your-template-id>";

const version = await client.documents.templates.versions.create(TEMPLATE_ID, {
  generation: {
    instructions: {
      prompt: "Produce a structured consultation note. Address the patient in second person.",
    },
    sections: [
      { sectionId: SECTION_ID_1, orderIndex: 0 },
      { sectionId: SECTION_ID_2, orderIndex: 1 },
      { sectionId: SECTION_ID_NEW, orderIndex: 2 },
    ],
  },
});

// Replace these with your values
const TEMPLATE_ID = "<your-template-id>";
const VERSION_ID = "<your-version-id>";

await client.documents.templates.versions.publish(TEMPLATE_ID, VERSION_ID);
A successful publish returns { "status": "published" } and subsequent GET /documents/templates/{templateID} reflects the new publishedVersion.
Publishing a template version validates that every referenced section has a published version. Fix any unpublished sections before retrying the publish.

​
Managing templates

ActionEndpoint
List templates (filter by lang, region, specialty, label, published)GET /documents/templates
Get a template (resolved, ready-to-use)GET /documents/templates/{templateID}
Update metadata (name, description, languages, regions, specialties, labels)PATCH /documents/templates/{templateID}
Soft-delete a templateDELETE /documents/templates/{templateID} — returns 409 Conflict if another template or section inherits from this template
List versions (raw)GET /documents/templates/{templateID}/versions
Get a specific version (raw — owned values + section refs)GET /documents/templates/{templateID}/versions/{versionID}
Soft-delete a versionDELETE /documents/templates/{templateID}/versions/{versionID}
PATCH /documents/templates/{templateID} only updates template-level metadata. To change the prompt or section composition, create a new version and publish it.
Resolved vs. raw — what each read returns.
  • GET /documents/templates/{templateID} returns the template resolved — all inheritance applied, sections fully expanded. This is the ready-to-consume shape.
  • GET /documents/templates/{templateID}/versions/{versionID} returns the version raw — only the values this template version explicitly owns, plus inheritFromId and sectionId references. Use this to determine which fields the template overrides versus which fields it inherits.
  • LIST /documents/templates/{templateID}/versions returns the same raw shape as the version GET.
Deletion visibility. After a template is soft-deleted, LIST /documents/templates no longer returns it, but GET /documents/templates/{templateID} and the version reads continue to work — useful for audit, debugging, and resolving templates still referenced by historical documents or inheritance chains.
DELETE returns 409 Conflict if another template or section inherits from the template you’re trying to delete. Resolve the dependency first (delete or re-parent the inheriting resources) before retrying the delete.

​
Listing and discovering templates

GET /documents/templates supports the same filtering shape as sections:
Query paramBehavior
langBCP-47 language subtag (e.g. fr, de). Repeatable. Matches templates whose languages[] contains any of the supplied values.
regionISO 3166-1 alpha-3 country code (e.g. BEL, USA). Repeatable. Matches templates whose regions[] contains any of the supplied values.
specialtyClinical specialty (e.g. dermatology, cardiology). Repeatable. Matches templates whose specialties[] contains any of the supplied values.
labelLabel filter in key:value format (e.g. ?label=customer:acme). Repeatable; matches templates that carry any of the given Label entries.
publishedOmit for both, true for published-only, false for unpublished-only.
// Filter by language, region, specialty, label, and/or publish status.
// All four filter params are repeatable arrays. `label` values use "key:value".
const templates = await client.documents.templates.list({
  lang: ["en"],
  region: ["USA"],
  specialty: ["dermatology"],
  label: ["customer:acme"],
  published: true,
});

​
Design tips

  • Author once, reuse everywhere. A single well-tuned corti-hpi-style section can power multiple templates. Avoid embedding section-specific guidance in templates.
  • Prefer narrow, focused sections. Sections that try to do too much are harder to reuse and harder to constrain via outputSchema.
  • Use labels for discovery. Labels are how you (and downstream consumers) filter sections and templates at list time.
  • Use inheritance for variants. Pediatric, geriatric or specialty-specific variants of a base template are a good fit for inheritFromId.

​
Next steps

Create a Section

Author and version the building blocks you’ll compose into templates.

Corti Standards

Browse the Corti-curated standard sections and templates available to every API client by default — useful as a starting point or as a base for inheritance.