> ## 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.

# Manage & discover sections & templates

> Read, update, delete and filter clinical document sections and templates on the Corti API — with resolved-vs-raw reads, soft-delete semantics, inheritance-aware deletion guards, and label-driven discovery across language, region and specialty

<Badge className="accent-badge" shape="rounded">Beta</Badge>

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 & 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 visibility.** After deletion, `LIST` no longer returns the resource, but `GET` on the resource ID and its version reads continue to work — useful for audit, debugging, and resolving resources still referenced by historical documents or inheritance chains.

***

## Managing sections

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

<Note>`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](/textgen/versioning).</Note>

## Managing templates

| Action                                                                                   | Endpoint                                                                                                                                                                          |
| :--------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| List templates (filter by `source`, `lang`, `region`, `specialty`, `label`, `published`) | [`GET /documents/templates`](/api-reference/guided-templates/list-templates)                                                                                                      |
| Get a template (resolved, ready-to-use)                                                  | [`GET /documents/templates/{templateID}`](/api-reference/guided-templates/get-template)                                                                                           |
| Update metadata (`name`, `description`, `languages`, `regions`, `specialties`, `labels`) | [`PATCH /documents/templates/{templateID}`](/api-reference/guided-templates/update-template-metadata)                                                                             |
| Soft-delete a template                                                                   | [`DELETE /documents/templates/{templateID}`](/api-reference/guided-templates/delete-template) — returns `409 Conflict` if another template or section inherits from this template |
| List versions (raw)                                                                      | [`GET /documents/templates/{templateID}/versions`](/api-reference/guided-templates/list-template-versions)                                                                        |
| Get a specific version (raw — owned values + section refs)                               | [`GET /documents/templates/{templateID}/versions/{versionID}`](/api-reference/guided-templates/get-template-version)                                                              |
| Soft-delete a version                                                                    | [`DELETE /documents/templates/{templateID}/versions/{versionID}`](/api-reference/guided-templates/delete-template-version)                                                        |

<Note>`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](/textgen/versioning).</Note>

***

## Discovery: filtering & 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; matches resources that carry any of the given `Label` entries.               |
| `published` | Omit for both, `true` for published-only, `false` for unpublished-only.                                                                                    |

<Note>**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.</Note>

### Listing sections

<CodeGroup>
  ```ts title="JavaScript" theme={null}
  // 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,
  });
  ```

  ```csharp title="C# .NET" theme={null}
  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,
      });
  ```

  ```python title="Python" theme={null}
  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()
  ```

  ```bash title="cURL" theme={null}
  # 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}"
  ```
</CodeGroup>

### Listing templates

<CodeGroup>
  ```ts title="JavaScript" theme={null}
  // 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,
  });
  ```

  ```csharp title="C# .NET" theme={null}
  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,
      });
  ```

  ```python title="Python" theme={null}
  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()
  ```

  ```bash title="cURL" theme={null}
  # 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}"
  ```
</CodeGroup>