Create Schema

Create a new schema with a name and definition in any of the three supported formats: JSON Schema, simplified fields, or flat key-type map.

Create a new schema to define the fields you want to extract from documents. The schema definition is normalized to JSON Schema format on creation, regardless of which input format you use.

Talonic accepts three definition formats to make schema creation flexible. You can pass a full JSON Schema object, a simplified fields array, or a flat key-type map. All three are converted to the same internal representation.

POST/v1/schemas

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" }
    }
  },
  "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_errorSchema definition produced no fields. Provide a valid JSON Schema, fields array, or flat key-type map.

401unauthorizedMissing or invalid API key.

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

Schema Formats

List Schemas