Manage & discover sections & templates

Beyond create and version, sections and templates share a uniform management + discovery surface: read resolved or raw, update metadata, soft-delete with inheritance guards, and filter LIST results by language, region, specialty and label. The endpoints below detail the per-resource specifics. The semantics — resolved-vs-raw reads, soft-delete conflicts, deletion visibility, and filter query params — are shared across both resource types.

Resolved vs. raw reads

Reads come in two shapes:

Resolved. GET /documents/sections/{sectionID} and GET /documents/templates/{templateID} return the resource resolved — all inheritance applied, sections fully expanded on templates. This is the ready-to-consume shape that will be used at generation time.
Raw. GET .../versions/{versionID} and LIST .../versions return the version raw — only the values this version explicitly owns, plus inheritFromId and (for templates) sectionId references. Use this when you need to distinguish inherited fields from fields the resource explicitly overrides.

Soft-delete and inheritance guards

DELETE on a section or template returns 409 Conflict if any other section or template inherits from it. Resolve the dependency first — delete or re-parent the inheriting resources — before retrying the delete.

Deletion is not Breaking. After deletion, LIST and GET no longer return the resource, but document generation still works. We opted for this behaviour to safeguard existing deployments from unintentional disruptions.

Managing sections

Action	Endpoint
List sections (filter by `source`, `lang`, `region`, `specialty`, `label`, `published`)	`GET /documents/sections`
Get a section (resolved, ready-to-use)	`GET /documents/sections/{sectionID}`
Update metadata (`name`, `description`, `languages`, `regions`, `specialties`, `labels`)	`PATCH /documents/sections/{sectionID}`
Soft-delete a section	`DELETE /documents/sections/{sectionID}` — returns `409 Conflict` if another section inherits from this one
List versions (raw)	`GET /documents/sections/{sectionID}/versions`
Get a specific version (raw — owned values only)	`GET /documents/sections/{sectionID}/versions/{versionID}`
Soft-delete a version	`DELETE /documents/sections/{sectionID}/versions/{versionID}`

PATCH /documents/sections/{sectionID} only updates section-level metadata. To change the prompts or output schema, create a new version and publish it — see Versioning.

Managing templates

Action	Endpoint
List templates (filter by `source`, `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 template	`DELETE /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 version	`DELETE /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 — see Versioning.

Discovery: filtering and listing

Both GET /documents/sections and GET /documents/templates accept the same set of query parameters. Use any combination — they’re additive.

Query param	Behavior
`lang`	BCP-47 language subtag (e.g. `fr`, `de`). Repeatable (e.g. `?lang=en&lang=da`). Matches resources whose `languages[]` contains any of the supplied values.
`region`	ISO 3166-1 alpha-3 country code (e.g. `BEL`, `USA`). Repeatable. Matches resources whose `regions[]` contains any of the supplied values.
`specialty`	Clinical specialty (e.g. `dermatology`, `cardiology`). Repeatable. Matches resources whose `specialties[]` contains any of the supplied values.
`label`	Label filter in `key:value` format (e.g. `?label=customer:acme`). Repeatable. Multiple values for the same key are OR-ed; multiple different keys are AND-ed. See Label filtering semantics below.
`published`	Omit for both, `true` for published-only, `false` for unpublished-only.

Empty languages, regions, or specialties means “no tweaks for that dimension” — the resource is generic along that axis. The fields are arrays but each one is optional and empty by default.

Label filtering semantics

When you repeat the label query parameter, the filtering logic is:

Multiple values for the same key → OR. A resource matches if it carries any of the given values for that key.
Multiple different keys → AND. A resource must carry at least one value for every key you supply.

Query	Matches resources that…
`?label=customer:acme`	carry `customer:acme`
`?label=customer:acme&label=customer:beta`	carry `customer:acme` OR `customer:beta`
`?label=customer:acme&label=department:cardiology`	carry `customer:acme` AND `department:cardiology`
`?label=customer:acme&label=customer:beta&label=department:cardiology`	carry (`customer:acme` OR `customer:beta`) AND `department:cardiology`

Example — OR within a key, AND across keys

GET /documents/templates?label=customer:acme&label=customer:beta&label=department:cardiology

Returns templates tagged with either customer:acme or customer:beta, and also tagged with department:cardiology.

The label query language is minimal today — flat key:value containment with AND/OR semantics. Richer query capabilities (negation, wildcards, scoped path expressions) are on the roadmap.

Listing sections

// Filter by language, region, specialty, label, and/or publish status.
// All four filter params are repeatable arrays. `label` values use "key:value".
const sections = await client.documents.sections.list({
  lang: ["en"],
  region: ["USA"],
  specialty: ["dermatology"],
  label: ["customer:acme"],
  published: true,
});

using Corti;

var sections = await client.Documents.Sections.ListAsync(
    new GuidedSectionsListRequest
    {
        Lang = new[] { "en" },
        Region = new[] { "USA" },
        Specialty = new[] { "dermatology" },
        Label = new[] { "customer:acme" },
        Published = true,
    });

import requests

# Replace these with your values
ENVIRONMENT = "<eu-or-us>"
TENANT = "<your-tenant-name>"
TOKEN = "<your-access-token>"

url = f"https://api.{ENVIRONMENT}.corti.app/v2/documents/sections"
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Tenant-Name": TENANT,
}

# `lang`, `region`, `specialty`, and `label` are repeatable; `label` uses "key:value".
params = [
    ("lang", "en"),
    ("region", "USA"),
    ("specialty", "dermatology"),
    ("label", "customer:acme"),
    ("published", "true"),
]
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
sections = response.json()

# Replace these with your values
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

# `lang`, `region`, `specialty`, and `label` are repeatable; `label` uses "key:value".
curl "https://api.${ENVIRONMENT}.corti.app/v2/documents/sections?lang=en&region=USA&specialty=dermatology&label=customer:acme&published=true" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Listing templates

// 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,
});

using Corti;

var templates = await client.Documents.Templates.ListAsync(
    new GuidedTemplatesListRequest
    {
        Lang = new[] { "en" },
        Region = new[] { "USA" },
        Specialty = new[] { "dermatology" },
        Label = new[] { "customer:acme" },
        Published = true,
    });

import requests

# Replace these with your values
ENVIRONMENT = "<eu-or-us>"
TENANT = "<your-tenant-name>"
TOKEN = "<your-access-token>"

url = f"https://api.{ENVIRONMENT}.corti.app/v2/documents/templates"
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Tenant-Name": TENANT,
}

# `lang`, `region`, `specialty`, and `label` are repeatable; `label` uses "key:value".
params = [
    ("lang", "en"),
    ("region", "USA"),
    ("specialty", "dermatology"),
    ("label", "customer:acme"),
    ("published", "true"),
]
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
templates = response.json()

# Replace these with your values
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

# `lang`, `region`, `specialty`, and `label` are repeatable; `label` uses "key:value".
curl "https://api.${ENVIRONMENT}.corti.app/v2/documents/templates?lang=en&region=USA&specialty=dermatology&label=customer:acme&published=true" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Getting Started

Core Capabilities

Manage Templates in Console

Endpoints

Best Practices & Resources

Documents Classic

Resolved vs. raw reads

Soft-delete and inheritance guards

Managing sections

Managing templates

Discovery: filtering and listing

Label filtering semantics

Listing sections

Listing templates

​Resolved vs. raw reads

​Soft-delete and inheritance guards

​Managing sections

​Managing templates

​Discovery: filtering and listing

​Label filtering semantics

​Listing sections

​Listing templates

Resolved vs. raw reads

Soft-delete and inheritance guards

Managing sections

Managing templates

Discovery: filtering and listing

Label filtering semantics

Listing sections

Listing templates