Update Schema

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

The PUT /v1/schemas/:id endpoint updates a saved extraction schema: its name, description, or field definition. 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