Skip to main content

Update, Publish & Lifecycle

Update the overlay draft, publish it to project fields and doctypes into the registry and classifier, unpublish to retract, or delete to remove it fully.

Updating an overlay edits its draft; if the overlay is already published, the update auto-forks a fresh draft so the live overlay is untouched until you publish again. PATCH semantics are per-array: doctypes and fields each replace their whole array when present and leave it unchanged when omitted — there is no per-item merge. name and description update the overlay header directly, independent of the draft content.

Publishing does three things atomically: it marks the latest version published, projects authored fields into your registry as pinned rows (protected from cleanup), and projects custom doctypes into the classifier on the overlay axis. Re-publishing after a rename also releases the superseded pins, so exactly one pinned registry row exists per authored concept. Unpublishing flips the published version back to a draft and reverses the projection; deleting removes the overlay (versions cascade) and reverses the projection too. The publish transaction is atomic — a failure mid-publish never leaves a published status with a half-projected registry.

Publish is also where the English machine key is derived: customers author field names in their own language, and publish derives an English snake_case english_key per field — the key extraction actually emits under. The derivation is recorded on the version (english_key_src = the authored name it came from, english_key_via = llm, or slug when the translation service was unavailable), and your authored name survives as the registry display name and as a synonym. A republish re-derives a key only when the authored name changed, so keys never drift under a stable name; slug-derived keys are retried on every publish until a real translation lands.

Publish, unpublish, and delete change extraction and classification behavior for your workspace. They are write-scope operations; treat publishing an overlay like a configuration change, not a read.
PATCH/v1/customer-ontologies/{id}

Body parameters

namestringRename the overlay (max 256 chars). Updates the header immediately, independent of drafts.
descriptionstringUpdate the description (max 2000 chars).
doctypesobject[]Replace the doctype set wholesale. Omit to leave the current doctypes unchanged.
fieldsobject[]Replace the field set wholesale. Omit to leave the current fields unchanged.
POST/v1/customer-ontologies/{id}/publish
POST/v1/customer-ontologies/{id}/unpublish
DELETE/v1/customer-ontologies/{id}

curl — stage an edit, then publish

curl -s -X PATCH https://api.talonic.com/v1/customer-ontologies/75feea55-70ef-4fac-92f6-73ef8e7556c1 \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"fields":[{"key":"delivery_date","display_name":"Delivery Date","data_type":"date","doctype_scope":"delivery_note"},{"key":"carrier_name","display_name":"Spediteur","data_type":"string","doctype_scope":"delivery_note"}]}'

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

Response (publish — field with a derived key)

{
  "id": "75feea55-70ef-4fac-92f6-73ef8e7556c1",
  "name": "Logistics",
  "status": "published",
  "latest_version": {
    "version": 2,
    "status": "published",
    "dirty": false,
    "published_at": "2026-08-29T14:10:22.501Z",
    "fields": [
      {
        "key": "carrier_name",
        "display_name": "Spediteur",
        "data_type": "string",
        "doctype_scope": "delivery_note",
        "english_key": "carrier_name",
        "english_key_src": "Spediteur",
        "english_key_via": "llm"
      }
    ]
  }
}

The lifecycle is designed so nothing changes out from under a running pipeline: updates land on a draft, publishing swaps the projection atomically, and unpublish or delete reverse it. Reversal is conservative on the registry side — authored rows are un-pinned, never deleted, since extracted occurrences may already bind to them; custom doctypes are only dropped when no document is classified under them. Concepts another still-published overlay declares are left intact. Verify the outcome with the [published-overlay preview endpoint](customer-ontology-mappings), which shows exactly the custom doctypes the classifier will apply.

Frequently asked questions

What happens to my registry when I unpublish?+
Unpublish reverses the projection: it un-pins the authored registry rows (they are kept, not deleted, since occurrences may bind) and drops custom doctypes no document is classified under. Concepts another still-published overlay declares are left intact.
Is publishing idempotent?+
Yes. Re-publishing upserts the pinned registry rows and matches doctypes by name, so publishing the same content twice is a no-op. English-key derivation is part of that: a key is re-derived only when its authored name changed since it was recorded.
What happens when I edit a published overlay?+
The update auto-forks a fresh draft version and edits that. The published version your pipelines read stays untouched until you publish again, so an in-flight run never sees a half-edited overlay.
Does PATCH merge my fields with the existing ones?+
No. When the doctypes or fields array is present in the body, it replaces that array wholesale on the draft; omitting the array leaves it unchanged. To add one field, send the full field list including the new one — the same rule the import endpoint follows.
Why is a field's english_key_via sometimes "slug"?+
Key derivation calls an LLM to translate your authored name into an English snake_case key; when that service is unavailable, publish falls back to a deterministic slug of the authored name rather than failing. Slug keys are degraded results and are retried on every subsequent publish until a real translation lands.

Related

Customer Overlays
Import an Overlay
Get & Version History
Map to Talonic Types
Field Registry