Skip to main content

Create Schema

Create a reusable extraction schema with POST /v1/schemas. Accepts JSON Schema, a flat key-type map, or a fields array, normalized to one JSON Schema shape.

The POST /v1/schemas endpoint creates a reusable extraction schema: the set of fields you want extracted from documents. Whatever input format you send, the stored definition is normalized to JSON Schema, and you can then pass the returned id as schema_id on POST /v1/extract for consistent, schema-driven extraction.

Talonic accepts three input formats so schema creation stays flexible. Two go in the definition body parameter, and the third is a separate top-level fields array. All three are converted to the same internal representation.

  • JSON Schema — Pass definition as a standard { "type": "object", "properties": { ... } } object with full control over types, titles, descriptions, and required fields.
  • Flat key-type map — Pass definition as a simple { "field_name": "string", "amount": "number" } object for the fastest path. Valid type values: string, number, boolean, date, enum, array, object.
  • Fields array — Pass a top-level fields array instead of definition. Each element carries a required field_name plus optional display_name, data_type, description, and is_required.
The inline schema parameter on POST /v1/extract has its own simplified-fields variant with name/type keys. The saved-schema fields array documented here uses field_name/data_type keys instead. See Schema Formats for the extract-side shapes.
POST/v1/schemas

Body parameters

name*stringHuman-readable name for the schema (max 100 characters).
definitionobjectSchema definition as JSON Schema or a flat key-type map. Optional: omit both definition and fields to create an empty schema.
fieldsarrayAlternative to definition: array of { field_name, display_name?, data_type?, description?, is_required? } objects.
descriptionstringOptional description of what this schema extracts.

Create a schema (JSON Schema definition)

Create a schema (flat key-type map)

Response

Response fields (201 Created)

idstringSchema UUID.
short_idstringHuman-readable short ID (e.g. SCH-A1B2C3D4).
namestringSchema name.
descriptionstring | nullOptional description.
definitionobjectNormalized JSON Schema definition.
field_countintegerNumber of fields created.
versionintegerSchema version (always 1 for new schemas).
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
linksobjectRelated resource URLs (self, extractions, dashboard).

Response (201 Created)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "short_id": "SCH-B2C3D4E5",
  "name": "Purchase Order",
  "description": null,
  "definition": {
    "type": "object",
    "properties": {
      "po_number": { "type": "string", "title": "PO Number" },
      "vendor": { "type": "string", "title": "Vendor" },
      "total": { "type": "number", "title": "Total" },
      "delivery_date": { "type": "date", "title": "Delivery Date" }
    },
    "required": ["po_number"]
  },
  "field_count": 4,
  "version": 1,
  "created_at": "2024-09-14T12:00:00.000Z",
  "updated_at": "2024-09-14T12:00:00.000Z",
  "links": {
    "self": "/v1/schemas/b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "extractions": "/v1/extractions?schema_id=b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "dashboard": "https://app.talonic.com/schemas/user/b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Errors

Error responses

400validation_errorThe provided definition or fields array produced no fields. Provide a valid JSON Schema, fields array, or flat key-type map.
401unauthorizedMissing or invalid API key.
403insufficient_scopeAPI key lacks the write scope required for this action.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Schema Formats
List Schemas
Update Schema
Extract with a Saved Schema