Schemas

Replace a schema

Replace a schema's name, description, and/or field definition. If definition.properties is provided, all existing fields are replaced.

put/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

No recorded changes to this operation across all 1 revision of this API.