Getting started
Submit a document, poll for the result, and extract structured data in minutes.
Prerequisites
You need an API key to authenticate requests. Keys use the format vnd_xxxxx and are included as a Bearer token in the Authorization header.
You can generate an API key from the web dashboard or request one from your account administrator.
curl https://api.helvetii.ai/projects \
-H "Authorization: Bearer vnd_your_api_key"Base URL
https://api.helvetii.ai
Submit a document
Base64-encode your PDF and send it to POST /process_file with a project and document type. The API returns a task_id for polling.
curl -X POST https://api.helvetii.ai/process_file \
-H "Authorization: Bearer vnd_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"file_base64": "'$(base64 -i invoice.pdf)'",
"project": "my_project",
"document_type": "invoice",
"max_pages": 10
}'import base64
import requests
api_key = "vnd_your_api_key"
base_url = "https://api.helvetii.ai"
with open("invoice.pdf", "rb") as f:
file_b64 = base64.b64encode(f.read()).decode()
response = requests.post(
f"{base_url}/process_file",
headers={"Authorization": f"Bearer {api_key}"},
json={
"file_base64": file_b64,
"project": "my_project",
"document_type": "invoice",
"max_pages": 10,
},
)
task_id = response.json()["task_id"]
print(f"Task created: {task_id}")Poll for results
Query GET /task_status/{task_id} until status is complete or failed. We recommend polling every 2 seconds.
import time
while True:
status = requests.get(
f"{base_url}/task_status/{task_id}",
headers={"Authorization": f"Bearer {api_key}"},
).json()
if status["status"] == "complete":
print(status["result"])
break
elif status["status"] == "failed":
print(f"Error: {status['error']}")
break
time.sleep(2)Tip
For production workloads, consider using webhooks instead of polling to receive results automatically.
Use the result
When the task completes, the result field contains the extracted data as structured JSON matching your schema definition.
{
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "complete",
"result": {
"invoice_number": "INV-2024-0042",
"date": "2024-11-15",
"vendor": "Acme Corp",
"total_amount": 1250.00,
"currency": "CHF",
"line_items": [
{
"description": "Consulting services",
"quantity": 5,
"unit_price": 250.00
}
]
},
"created_at": "2024-11-15T10:30:00Z",
"updated_at": "2024-11-15T10:30:12Z"
}