Save Talonic Schema
talonic_save_schemaSave a schema definition to your workspace for reuse across multiple document extractions, standardizing extraction for consistent results.
Instructions
STATUS: stable.
Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id.
USE WHEN:
The user asks to save a schema, store a template, or reuse the schema across docs.
You have iterated on a schema with the user and they confirmed it should be saved.
The user wants to standardise extraction across many documents of the same type.
DO NOT USE WHEN:
The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline).
The user has not confirmed the schema design (avoid creating clutter in their workspace).
DEFINITION FORMATS:
JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } }
Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema.
TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the schema, e.g. 'Standard Invoice'. | |
| definition | Yes | Schema definition. Most reliable: full JSON Schema {type:'object', properties:{...}}. Also accepted: a flat key-type map {field_name:'string', amount:'number'} which the API normalises. | |
| description | No | Optional description of what this schema extracts and when to use it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | UUID of the newly saved schema. | |
| short_id | No | Human-readable short id (SCH-XXXXXXXX). | |
| name | Yes | ||
| description | No | Schema description, or null when the schema was saved without one. The API explicitly maps the absent case to null (see SchemaResponse in openapi.yaml). | |
| definition | No | Final schema definition as stored, normalised by the API. | |
| field_count | No | ||
| version | No | Schema version (1 for new schemas; increments on update). | |
| created_at | No | ||
| updated_at | No | ||
| links | No |