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
definitionas a standard{ "type": "object", "properties": { ... } }object with full control over types, titles, descriptions, andrequiredfields. - Flat key-type map — Pass
definitionas 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
fieldsarray instead ofdefinition. Each element carries a requiredfield_nameplus optionaldisplay_name,data_type,description, andis_required.
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./v1/schemasBody parameters
Create a schema (JSON Schema definition)
curl -X POST https://api.talonic.com/v1/schemas \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Purchase Order",
"definition": {
"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"]
}
}'Create a schema (flat key-type map)
curl -X POST https://api.talonic.com/v1/schemas \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Purchase Order",
"definition": {
"po_number": "string",
"vendor": "string",
"total": "number",
"delivery_date": "date"
}
}'Response
Response fields (201 Created)
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
Frequently asked questions
Which schema definition format should I use?+
{ "field": "type" }) for quick prototyping and JSON Schema for production schemas that need required fields, display titles, or per-field descriptions. The fields array is convenient when your field list already lives in tabular form.What happens if my definition has no valid fields?+
definition or fields value that produces zero fields after normalization, the API returns a 400 validation_error. If you omit both entirely, the schema is created empty and you can add fields later with PUT /v1/schemas/:id.Is the version always 1 for new schemas?+
GET /v1/schemas/:id/versions.How do I extract data using a saved schema?+
id as the schema_id parameter on POST /v1/extract. Every extraction run with that schema_id returns the same field structure defined by the schema.