Schemas

Update a schema

Partially update a schema. name and description are patched independently; omitted keys are left unchanged. If definition.properties or a non-empty fields array is provided, all existing fields are replaced with the new set. PUT on this path delegates to the same handler, so both methods accept the same body and behave identically. Schemas managed by a Spec document are read-only through the public API and return 409 Conflict.

patch/v1/schemas/{id}

Request

  • Base URL: https://api.talonic.com
  • URL: https://api.talonic.com/v1/schemas/{id}
  • Auth: HTTP bearer

Path parameters

idstring uuid required
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Resource UUID.

Request body

namestring
descriptionstring nullable

Example request

{
  "fields": [
    {
      "field_name": "invoice_number",
      "display_name": "Invoice Number",
      "data_type": "string"
    }
  ]
}

Response

Schema updated.

idstring uuid required
short_idstring

Short form of id (SCH- + the first 8 hex characters, uppercased). Accepted wherever {id} is.

spec_idstring uuid nullable

The Spec that authors this schema, or null when the schema was created directly (via POST /v1/schemas or the legacy editor). This is the id in the Spec editor URL (/specs/{spec_id}) and is a DIFFERENT id from the schema id above — a Spec is materialized onto a schema, it is not the same record. Use this to cross between the two.

spec_versioninteger nullable

The Spec's published head version — the number shown in the Spec editor. null when spec_id is null, or when the Spec has never been published. Not the same counter as version below.

spec_materialized_versioninteger nullable

The Spec version whose configuration is live on this schema — what a run of it actually executes. Normally equal to spec_version; it lags when a publish was refused by the acknowledgement gate or a stale activation no-opped. null when spec_id is null.

namestring required
descriptionstring nullable
field_countinteger
versioninteger

Legacy schema-version counter, advanced by the version endpoints (/v1/schemas/{id}/versions). A Spec-authored schema never advances it — read spec_version for those.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "short_id": "SCH-A1B2C3D4",
  "spec_id": "e2144027-39c0-44e8-a196-72be1e360749",
  "spec_version": 3,
  "spec_materialized_version": 3,
  "name": "Invoice Schema",
  "description": "Standard invoice fields for AP processing.",
  "definition": {
    "type": "object",
    "properties": {
      "invoice_number": {
        "type": "string",
        "title": "Invoice Number"
      },
      "total_amount": {
        "type": "number",
        "title": "Total Amount",
        "description": "Total invoice amount including tax"
      }
    },
    "required": [
      "invoice_number"
    ]
  },
  "field_count": 8,
  "version": 1,
  "created_at": "2026-04-25T14:30:00.000Z",
  "updated_at": "2026-04-25T14:30:00.000Z"
}

Changes