Update Schema

Replace a schema definition, creating a new version internally. Existing extractions retain their original schema version.

Replace a schema's definition, name, or description. Each update creates a new version internally, so you can track how a schema evolves over time. Existing extractions are not affected by schema updates — they retain the schema version that was active when they were created.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "short_id": "SCH-A1B2C3D4",
  "name": "Invoice v2",
  "description": "Updated invoice schema with line items",
  "definition": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string", "title": "invoice_number" },
      "vendor": { "type": "string", "title": "vendor" },
      "total": { "type": "number", "title": "total" },
      "date": { "type": "date", "title": "date" },
      "line_items": { "type": "array", "title": "line_items" }
    },
    "required": ["invoice_number"]
  },
  "field_count": 5,
  "version": 1,
  "created_at": "2024-08-20T14:00:00.000Z",
  "updated_at": "2024-09-15T10:30:00.000Z",
  "links": {
    "self": "/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "extractions": "/v1/extractions?schema_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "dashboard": "https://app.talonic.com/schemas/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Most integrations call this endpoint when extraction requirements evolve — for example, adding a new field to an invoice schema or renaming an existing one. A typical workflow is to fetch the current schema with GET /v1/schemas/:id, modify the definition, then send the updated payload here.

The response includes the updated definition, field_count, and version number. The updated_at timestamp reflects when the change was applied. All body parameters are optional — send only name, definition, or description to update that field without touching the others.

Pair this with GET /v1/extractions?schema_id=:id to review historical extractions that used previous versions. Note that schema versioning is append-only internally, so you can always compare before-and-after definitions through the dashboard.

Errors