Templates

Templates define how the AI extracts data from your documents — the schema fields, instructions, and output format. The Templates endpoints let you manage templates programmatically, including uploading reference data files that guide the AI during extraction.

List Templates

GET /v1/openapi/templates

Returns all templates accessible to the token. Organization tokens return templates across all projects in the organization; project tokens return templates for their scoped project only.

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Example Request:

curl "https://api.ocriva.com/v1/openapi/templates" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

[
  {
    "templateId": "68db4bb3a67e9c04fb0c6f85",
    "name": "Invoice Template",
    "description": "Extract structured data from invoices including line items, totals, and vendor details",
    "templateSchema": {
      "invoiceNumber": { "type": "string", "description": "Invoice number" },
      "totalAmount": { "type": "number", "description": "Total invoice amount" },
      "vendor": { "type": "string", "description": "Vendor name" }
    },
    "projectId": "68db4aa2967d9c03fa9b5e74",
    "isActive": true,
    "resultFormat": "json",
    "extractionMode": "structured",
    "createdAt": "2026-01-15T08:00:00.000Z",
    "updatedAt": "2026-03-20T14:30:00.000Z"
  }
]

Create Template

POST /v1/openapi/templates

Creates a new extraction template for a project.

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes
`Content-Type`	`application/json`	Yes

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Template name (e.g., `Receipt`)
`description`	string	Yes	What this template extracts
`templateSchema`	object	Yes	JSON Schema defining the fields to extract
`projectId`	string	Yes	Target project ID
`instructions`	string	No	Custom AI assistant instructions

Example Request:

curl -X POST "https://api.ocriva.com/v1/openapi/templates" \
  -H "X-API-Key: ocr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Receipt",
    "description": "Extract structured data from receipts including merchant information, items purchased, amounts, and payment details",
    "projectId": "68db4aa2967d9c03fa9b5e74",
    "templateSchema": {
      "merchantName": {
        "type": "string",
        "description": "Name of the merchant or store"
      },
      "totalAmount": {
        "type": "number",
        "description": "Total amount paid including tax"
      },
      "date": {
        "type": "string",
        "description": "Date of the transaction (YYYY-MM-DD)"
      },
      "items": {
        "type": "array",
        "description": "List of purchased items"
      }
    },
    "instructions": "You are an expert in document analysis. Extract all fields accurately."
  }'

Example Response (201 Created):

{
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "name": "Receipt",
  "description": "Extract structured data from receipts including merchant information, items purchased, amounts, and payment details",
  "templateSchema": {
    "merchantName": { "type": "string", "description": "Name of the merchant or store" },
    "totalAmount": { "type": "number", "description": "Total amount paid including tax" },
    "date": { "type": "string", "description": "Date of the transaction (YYYY-MM-DD)" },
    "items": { "type": "array", "description": "List of purchased items" }
  },
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "isActive": true,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T10:00:00.000Z"
}

Update Template

PUT /v1/openapi/templates/:id

Updates an existing template. Only the fields you provide are changed.

Path Parameters:

Parameter	Description
`id`	Template ID to update

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes
`Content-Type`	`application/json`	Yes

Request Body:

Field	Type	Required	Description
`projectId`	string	Yes	Project ID the template belongs to
`name`	string	No	Updated template name
`description`	string	No	Updated description
`templateSchema`	object	No	Updated schema definition
`instructions`	string	No	Updated AI instructions

Example Request:

curl -X PUT "https://api.ocriva.com/v1/openapi/templates/68db4bb3a67e9c04fb0c6f85" \
  -H "X-API-Key: ocr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "68db4aa2967d9c03fa9b5e74",
    "name": "Receipt Updated",
    "description": "Updated description for receipt processing"
  }'

Example Response (200 OK):

{
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "name": "Receipt Updated",
  "description": "Updated description for receipt processing",
  "templateSchema": {
    "merchantName": { "type": "string", "description": "Name of the merchant or store" },
    "totalAmount": { "type": "number", "description": "Total amount paid including tax" }
  },
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "isActive": true,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T11:15:00.000Z"
}

Common Errors:

Status	Cause
`401`	Template does not belong to the token's project or organization
`404`	Template not found

Delete Template

DELETE /v1/openapi/templates/:id

Soft-deletes a template. The template is marked inactive and will no longer appear in list responses, but historical processing records that reference it are preserved.

Path Parameters:

Parameter	Description
`id`	Template ID to delete

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Example Request:

curl -X DELETE "https://api.ocriva.com/v1/openapi/templates/68db4bb3a67e9c04fb0c6f85" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "message": "Template deleted successfully"
}

Common Errors:

Status	Cause
`401`	Template does not belong to the token's project or organization
`404`	Template not found

Upload Data File to Template

POST /v1/openapi/templates/:id/files

Attaches a reference data file (JSON, Markdown, or plain text) to a template. The AI uses these files as additional context during extraction — for example, a product catalog or a list of merchant codes.

Path Parameters:

Parameter	Description
`id`	Template ID to attach the file to

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes
`Content-Type`	`multipart/form-data`	Yes

Request Body (multipart/form-data):

Field	Type	Required	Description
`file`	File	Yes	Data file to attach. Accepted types: `.json`, `.md`, `.txt`

Example Request:

curl -X POST "https://api.ocriva.com/v1/openapi/templates/68db4bb3a67e9c04fb0c6f85/files" \
  -H "X-API-Key: ocr_your_api_key" \
  -F "file=@/path/to/product-catalog.json"

Example Response (201 Created):

{
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "name": "Receipt",
  "description": "Extract structured data from receipts",
  "templateSchema": { ... },
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "isActive": true,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T12:00:00.000Z"
}

Common Errors:

Status	Cause
`400`	No file included, or unsupported file type
`401`	Template does not belong to the token's scope
`404`	Template not found

Remove Data File from Template

DELETE /v1/openapi/templates/:id/files/:fileId

Removes a previously attached data file from a template.

Path Parameters:

Parameter	Description
`id`	Template ID
`fileId`	Data file ID to remove

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Example Request:

curl -X DELETE "https://api.ocriva.com/v1/openapi/templates/68db4bb3a67e9c04fb0c6f85/files/68dc2dd5c89f1e26fd3b8g02" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "name": "Receipt",
  "description": "Extract structured data from receipts",
  "templateSchema": { ... },
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "isActive": true,
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T12:30:00.000Z"
}

Common Errors:

Status	Cause
`401`	Template does not belong to the token's scope
`404`	Template or file not found

Documents

Templates

Templates

List Templates

Create Template

Update Template

Delete Template

Upload Data File to Template

Remove Data File from Template

Table of Contents