Get Schema

Retrieve a schema by ID including its full definition with all field names, data types, extraction instructions, and configuration options. Returns version history and extraction count.

Retrieve the full details of a single schema, including its JSON Schema definition, field count, and version number. Use this to inspect a schema before running extractions or to verify that an update was applied correctly.

You can pass either a UUID or a SCH- prefixed short ID (e.g. SCH-A1B2C3D4) as the :id path parameter.

GET/v1/schemas/:id

Response

Response fields

idstringSchema UUID.

short_idstringHuman-readable short ID (e.g. SCH-A1B2C3D4).

namestringSchema name.

descriptionstring | nullOptional description.

definitionobjectJSON Schema definition with type, properties, and required.

field_countintegerNumber of fields in the schema.

versionintegerSchema version number.

created_atstringISO 8601 creation timestamp.

updated_atstringISO 8601 last update timestamp.

linksobjectRelated resource URLs (self, extractions, dashboard).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "short_id": "SCH-A1B2C3D4",
  "name": "Invoice",
  "description": "Standard invoice extraction schema",
  "definition": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string", "title": "invoice_number", "description": "Unique invoice identifier" },
      "vendor": { "type": "string", "title": "vendor" },
      "total": { "type": "number", "title": "total" },
      "date": { "type": "date", "title": "date" }
    },
    "required": ["invoice_number"]
  },
  "field_count": 4,
  "version": 1,
  "created_at": "2024-08-20T14:00:00.000Z",
  "updated_at": "2024-09-10T09:15: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 before running an extraction to verify the schema definition is correct, or after an update to confirm the new version was applied. A typical workflow is to create a schema with POST /v1/schemas, store the returned id, then fetch it here whenever you need the current definition.

The response includes the full definition object in normalized JSON Schema format, along with the version number and field_count. Use the links.extractions URL to list all extractions that used this schema, and links.dashboard to open it in the platform UI.

Pair this with PUT /v1/schemas/:id to update the definition, or pass the id as schema_id on POST /v1/extract to run schema-driven extraction. Note that both UUID and SCH- prefixed short IDs are accepted as the :id parameter.

Errors

Error responses

400validation_errorInvalid schema identifier format. Use a UUID or SCH- short ID.

401unauthorizedMissing or invalid API key.

404schema_not_foundNo schema with this ID exists for your organization.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

List Schemas

Update Schema