Schemas
Schemas define the structure of the data you want to extract from your documents. A schema's definition is a JSON Schema object — it describes each field's type and, optionally, which fields are required. Once created, a schema can be reused across many documents.
Schema Definition
The schema field is a standard JSON Schema object. Use properties to declare the fields to extract, and required to mark the ones that must be present:
{
"type": "object",
"properties": {
"invoice_number": { "type": "string", "description": "Invoice number" },
"issue_date": { "type": "string", "description": "Issue date (YYYY-MM-DD)" },
"total": { "type": "number", "description": "Total amount" },
"vendor_name": { "type": "string", "description": "Vendor name" }
},
"required": ["invoice_number", "total"]
}Endpoints
GET /v1/schemas
Returns a paginated list of extraction schemas belonging to your team. List items include only the schema's identity (id, name, description) — fetch a single schema to retrieve its full definition.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 1 | Page number (min: 1) |
limit | number | No | 20 | Items per page (min: 1, max: 100) |
sort_by | string | No | created_at | Sort field: created_at or name |
sort_order | string | No | desc | Sort direction: asc or desc |
created_after | string | No | — | ISO 8601 date — schemas created on or after this date |
created_before | string | No | — | ISO 8601 date — schemas created on or before this date |
Request
curl -H "x-api-key: wk_xxxxxxxx.your_secret_here" \
"https://api.exelensia.com/v1/schemas?page=1&limit=20"Response
{
"data": [
{
"id": "019760a0-0001-7000-8000-000000000001",
"name": "Invoice Schema",
"description": "Extract invoice number, date, total, and vendor"
}
],
"meta": {
"total": 1,
"page": 1,
"limit": 20,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Status Codes
| Status | Description |
|---|---|
200 | Success |
401 | Missing or invalid authentication |
GET /v1/schemas/:id
Returns a single schema by ID, including its full JSON Schema definition.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Schema UUID |
Request
curl -H "x-api-key: wk_xxxxxxxx.your_secret_here" \
"https://api.exelensia.com/v1/schemas/019760a0-0001-7000-8000-000000000001"Response
{
"id": "019760a0-0001-7000-8000-000000000001",
"name": "Invoice Schema",
"description": "Extract invoice number, date, total, and vendor",
"schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string", "description": "Invoice number" },
"issue_date": { "type": "string", "description": "Issue date (YYYY-MM-DD)" },
"total": { "type": "number", "description": "Total amount" },
"vendor_name": { "type": "string", "description": "Vendor name" }
},
"required": ["invoice_number", "total"]
},
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z"
}Status Codes
| Status | Description |
|---|---|
200 | Success |
401 | Missing or invalid authentication |
404 | Schema not found |
POST /v1/schemas
Creates a new extraction schema.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable schema name |
description | string | No | Optional description |
schema | object | Yes | JSON Schema definition (see Schema Definition) |
curl -X POST \
-H "x-api-key: wk_xxxxxxxx.your_secret_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Contract Schema",
"description": "Extract key contract fields",
"schema": {
"type": "object",
"properties": {
"party_a": { "type": "string", "description": "First party" },
"party_b": { "type": "string", "description": "Second party" },
"effective_date": { "type": "string", "description": "Effective date (YYYY-MM-DD)" },
"value": { "type": "number", "description": "Contract value" }
},
"required": ["party_a", "party_b"]
}
}' \
"https://api.exelensia.com/v1/schemas"Response
Returns the created schema's identity. Fetch it with GET /v1/schemas/:id to retrieve the stored definition.
{
"id": "019760a0-0002-7000-8000-000000000002",
"name": "Contract Schema",
"description": "Extract key contract fields"
}If your team already has a schema with the same name, the new one is created with a timestamp suffix so names stay unique.
Status Codes
| Status | Description |
|---|---|
201 | Schema created |
400 | Invalid request body |
401 | Missing or invalid authentication |
DELETE /v1/schemas/:id
Deletes a schema by ID. A schema cannot be deleted while it has active process jobs (status queued or processing).
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Schema UUID |
Request
curl -X DELETE \
-H "x-api-key: wk_xxxxxxxx.your_secret_here" \
"https://api.exelensia.com/v1/schemas/019760a0-0001-7000-8000-000000000001"Response
Returns an empty 200 OK response on success.
Status Codes
| Status | Description |
|---|---|
200 | Schema deleted |
401 | Missing or invalid authentication |
404 | Schema not found |
409 | Schema has active process jobs and cannot be deleted |