Get & Version History

Read a Customer Overlay by ID: the header plus its latest doctypes and fields, and the full draft/publish version history as an audit trail, newest first.

Read a single Customer Overlay by id to get its header plus the content of its latest version (its doctypes and fields), embedded as latest_version. List its versions to see the full draft/publish history, newest first. Each publish and each auto-fork is a version, so the history is the audit trail of how the overlay evolved.

Use the detail read to render an authoring UI or to verify what is currently live before publishing again. Use the version list when you need to answer "what did the overlay look like when that batch was processed": the version that was published at the time is the configuration classification and extraction saw. The version list returns lightweight rows — id, version, status, dirty, published_at, created_at — without the doctype/field payloads, so it stays cheap to poll even for an overlay with a long history.

The dirty flag on a version marks unpublished edits: it is set whenever the draft's content changes and cleared on publish. A published overlay whose latest version is dirty: false is exactly what was deployed; a dirty: true draft on top of a published version means there are staged edits not yet live. On published fields you will also see the derived english_key (with english_key_src and english_key_via) alongside your authored names — the machine key extraction emits under, derived at publish time.

To review staged changes before a publish, read both sides and diff them: this detail read gives the draft's doctypes and fields, and the [published-overlay preview](customer-ontology-mappings) (GET /v1/customer-ontologies/overlay/doctypes) gives the doctypes currently live in the classifier. The pair answers "what will this publish change" without any extra bookkeeping on your side, which matters because publish deploys configuration to the live extraction path the moment it returns.

GET/v1/customer-ontologies/{id}

Path parameters

id*uuidOverlay UUID. 404 when no overlay with this id exists in your organization.

GET/v1/customer-ontologies/{id}/versions

curl

curl -s https://api.talonic.com/v1/customer-ontologies/75feea55-70ef-4fac-92f6-73ef8e7556c1 \
  -H "Authorization: Bearer tlnc_your_api_key"

curl -s https://api.talonic.com/v1/customer-ontologies/75feea55-70ef-4fac-92f6-73ef8e7556c1/versions \
  -H "Authorization: Bearer tlnc_your_api_key"

Response (versions)

[
  {
    "id": "31b2b0d4-1f2e-4c1a-9a63-2f8c3f6f8a11",
    "version": 2,
    "status": "draft",
    "dirty": true,
    "published_at": null,
    "created_at": "2026-08-29T14:02:07.114Z"
  },
  {
    "id": "7c48bade-35ba-4745-95ba-5523728a95be",
    "version": 1,
    "status": "published",
    "dirty": false,
    "published_at": "2026-08-29T11:33:41.428Z",
    "created_at": "2026-08-29T11:33:31.689Z"
  }
]

Response fields (detail read)

id / name / description / statusmixedThe overlay header. status is draft or published.

current_version_iduuidThe version the overlay currently points at.

latest_versionobjectThe newest version in full: version number, status, dirty, published_at, and the complete doctypes[] and fields[] arrays.

latest_version.doctypes[]arrayAuthored custom doctypes: key, name, category, maps_to, signals.

latest_version.fields[]arrayAuthored field concepts. Published fields additionally carry english_key, english_key_src, and english_key_via (llm or slug).

The detail read returns the latest version's content, which may be an unpublished draft. To see what the classifier is actually applying right now, use the published-overlay preview endpoint (GET /v1/customer-ontologies/overlay/doctypes) instead.

Frequently asked questions

What is in a version?+

Each version snapshots the overlay's doctypes and fields and its status (draft or published). Editing a published overlay auto-forks a new draft version, so the published one your pipelines read is immutable.

Does the detail read return the draft or the published version?+

The latest version, which is the draft when one exists. Use `GET /v1/customer-ontologies/overlay/doctypes` to see the published doctypes the classifier currently applies.

Why does the version history matter?+

It is the audit trail of the overlay: every publish and every auto-fork is recorded as a version, so you can reconstruct which doctypes and fields were live when any given batch of documents was processed.

What does the dirty flag mean?+

That the version has content edits not yet published. It is set on every draft write and cleared by publish, so dirty: true on the latest version tells you staged changes exist that the live projection does not reflect.

What are english_key, english_key_src, and english_key_via on a field?+

The English snake_case machine key the field projects and primes under, derived at publish time so you can author in any language. english_key_src records the authored name it was derived from, and english_key_via records how (llm, or slug when the translation service was unavailable — slugs are retried on the next publish).

Get & Version History

Frequently asked questions

Related