Update Schema

Update a schema name, description, or field definition with PATCH or PUT /v1/schemas/:id. Field changes replace the full field set; results are unchanged.

PATCH /v1/schemas/:id updates a saved extraction schema: its name, description, or field definition. PUT on the same path delegates to the identical handler, so both methods accept the same body and behave the same way. When you provide a definition with properties (or a non-empty fields array), the schema's existing fields are replaced with the new set. Already-completed extractions are not affected: their stored results keep the values extracted when they ran.

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. Because a provided definition.properties replaces the full field set, the safe workflow is to fetch the current schema with GET /v1/schemas/:id, modify the returned definition, then send the complete updated payload here.

The response includes the updated definition and field_count. The updated_at timestamp reflects when the change was applied. All body parameters are optional: send only name or only description to update metadata without touching the fields at all.

To audit how a schema evolved, use the versions endpoints: GET /v1/schemas/:id/versions lists published versions newest first, GET /v1/schemas/:id/versions/diff?from=<n>&to=<n> shows field-level changes between two versions, and POST /v1/schemas/:id/versions/rollback restores an earlier one.

Errors