API reference
Complete endpoint documentation. All requests use base URL https://api.helvetii.ai.
Authentication
The API supports two authentication methods. Each endpoint specifies which method it accepts.
Bearer token with vnd_ prefix. For programmatic access and machine-to-machine communication.
JWT token from Auth0. For frontend applications and user-facing integrations.
Document processing
Submit documents for AI-powered extraction and poll for results.
Submit a document for processing
Parameters
file_base64
Base64-encoded PDF or image
project
Project name (deprecated, use project_id)
project_id
Project UUID
document_type
Document type name
document_type_id
Document type UUID
schema
JSON schema that overrides the stored schema for this request only. See schema best practices.
max_pages
Maximum pages to process (default: 10)
high_precision
Use high precision OCR (default: false)
force_ocr
Bypass OCR cache (default: false)
file_name
Original filename for context
Example Request
{
"file_base64": "JVBERi0xLjQKJ...",
"project": "my_project",
"document_type": "invoice",
"max_pages": 10,
"high_precision": false,
"force_ocr": false,
"file_name": "invoice.pdf"
}Example Response
{
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Get task status and results
Parameters
task_id
Task ID from process_file response
auth_method
Query param: api_key (default) or auth0
Example Response
{
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "complete",
"result": {
"invoice_number": "INV-2024-0042",
"date": "2024-11-15",
"total_amount": 1250.00
},
"error": null,
"created_at": "2024-11-15T10:30:00Z",
"updated_at": "2024-11-15T10:30:12Z"
}Note
Status transitions: not_started → in_progress → complete | failed. The result field is populated only when status is complete.
Projects
Manage projects. All project endpoints require Auth0 authentication.
List all projects
Example Response
{
"projects": [
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "my-project",
"description": "Invoice processing pipeline",
"created_at": "2024-11-15T10:00:00Z",
"updated_at": "2024-11-15T10:00:00Z"
}
]
}Create a project
Parameters
name
Alphanumeric, hyphens, underscores, dots
description
Project description
default_schema_template
Default schema JSON
Example Request
{
"name": "my-project",
"description": "Invoice processing pipeline",
"default_schema_template": "{}"
}Example Response
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "my-project",
"description": "Invoice processing pipeline",
"default_schema_template": "{}",
"created_at": "2024-11-15T10:00:00Z",
"updated_at": "2024-11-15T10:00:00Z"
}Get project details
Parameters
project_id
Project UUID
Example Response
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "my-project",
"description": "Invoice processing pipeline",
"default_schema_template": "{}",
"created_at": "2024-11-15T10:00:00Z",
"updated_at": "2024-11-15T10:00:00Z"
}Update a project
Parameters
project_id
Project UUID
name
New project name
description
New description
Delete a project
Parameters
project_id
Project UUID
Document types
Manage document types and their extraction schemas. All endpoints require Auth0 authentication.
List document types
Parameters
project_id
Filter by project (query param)
Create a document type
Parameters
project_id
Parent project UUID
name
Document type name
description
Description
schema_definition
JSON schema for extraction fields
validation_rules
Business validation rules
field_importance
Field importance levels
Example Request
{
"project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "invoice",
"description": "Standard invoice extraction",
"schema_definition": {
"invoice_number": {
"type": "string",
"description": "Unique invoice identifier"
},
"date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format"
},
"vendor": {
"type": "string",
"description": "Vendor or supplier name"
},
"total_amount": {
"type": "number",
"description": "Total amount including tax"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code"
},
"line_items": {
"type": "array",
"description": "List of invoice line items",
"items": {
"description": { "type": "string" },
"quantity": { "type": "number" },
"unit_price": { "type": "number" }
}
}
},
"validation_rules": [],
"field_importance": {
"invoice_number": "critical",
"total_amount": "critical",
"date": "high",
"vendor": "high",
"line_items": "medium"
}
}Example Response
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "invoice",
"description": "Standard invoice extraction",
"schema_definition": { ... },
"validation_rules": [],
"field_importance": { ... },
"has_routine": false,
"created_at": "2024-11-15T10:05:00Z",
"updated_at": "2024-11-15T10:05:00Z"
}Get document type details
Parameters
document_type_id
Document type UUID
Update a document type
Parameters
document_type_id
Document type UUID
name
New name
schema_definition
Updated schema
Delete a document type
Parameters
document_type_id
Document type UUID
Status codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 204 | Resource deleted (no content) |
| 400 | Invalid request body or parameters |
| 401 | Missing or invalid authentication |
| 402 | Payment required (subscription inactive) |
| 404 | Resource not found or not owned by user |
| 422 | Validation error |
| 500 | Internal server error |