API Reference

The Veralens REST API is a small, predictable surface. Every endpoint lives under one base URL, speaks JSON, and returns the same envelope shape whether it succeeds or fails.

https://veralens.ai/api/v1

Authentication

Programmatic requests authenticate with an API key as a Bearer token. Create keys under API Keys in the dashboard. Each secret starts with vl_ and is shown once.

Authorization: Bearer vl_your_secret_key

Key management endpoints (create, list, rotate, revoke) are part of the dashboard and use your logged-in session. You cannot manage keys with an API key. Everything below under Jobs accepts an API key.

Response envelope

Success responses wrap the payload in data:

{ "status": "success", "data": { "id": "V1StGXR8_Z5jdHi6B", "status": "pending" } }

Errors carry a stable error_code plus a matching HTTP status:

{ "status": "error", "error_code": "insufficient_balance" }

Branch on the HTTP status and error_code. The codes are stable, and human-readable text is advisory only.

POST /jobs/create

Create an extraction job. Returns immediately with a job id; the work runs asynchronously.

Body

You must send at least one of schema or target. Provide a schema for strict typed JSON, or only a target (with an optional global_prompt) for freeform Markdown/plaintext or schemaless JSON.

Source types

Document limits, all returned as 400:

• 20 MB per file, measured on the decoded file, not the base64 text (job_document_too_large).
• 200 pages per PDF (job_document_too_many_pages).
• 800,000 characters of text per Word, Excel, CSV, text or Markdown file (job_document_content_too_large).

PDFs are read page by page as images. The other document types are read as text.

Response: 201 Created. Returns the full job object (same shape as GET /jobs/:jobId/get below), already in pending. model, target, and the hold (usage.cost) are set immediately. output and settled token usage fill in once the job runs.

{
  "status": "success",
  "data": {
    "id": "V1StGXR8_Z5jdHi6B",
    "status": "pending",
    "createdAt": "2025-03-01T10:15:00.000Z",
    "source": "key",
    "target": "json",
    "sources": { "images": 1, "texts": 0, "documents": 0 },
    "model": "vera-1.0-high",
    "usage": { "cost": 0.0021, "inputTokens": null, "outputTokens": null },
    "output": null,
    "durationMs": null
  }
}

Example

curl -X POST https://veralens.ai/api/v1/jobs/create \
  -H "Authorization: Bearer vl_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{ "type": "image", "data": "data:image/png;base64,iVBORw0KGgo..." }],
    "engine": "vera-1.0-high",
    "schema": {
      "type": "object",
      "properties": {
        "merchant": { "type": "string", "description": "Store or merchant name." },
        "total":    { "type": "number", "description": "Grand total paid." }
      },
      "required": ["merchant", "total"]
    }
  }'

GET /jobs/:jobId/get

Fetch a single job by id. Poll this until status is no longer pending.

Response

{
  "status": "success",
  "data": {
    "id": "V1StGXR8_Z5jdHi6B",
    "status": "completed",
    "createdAt": "2025-03-01T10:15:00.000Z",
    "source": "key",
    "target": "json",
    "sources": { "images": 1, "texts": 0, "documents": 0 },
    "model": "vera-1.0-high",
    "usage": { "cost": 0.0031, "inputTokens": 812, "outputTokens": 44 },
    "output": "{\"merchant\":\"Acme\",\"total\":19.9}",
    "durationMs": 2100
  }
}

Job fields

GET /jobs/list

List your jobs, most recent first.

Query parameters

Response

{
  "status": "success",
  "data": {
    "jobs": [ { "id": "V1StGXR8_Z5jdHi6B", "status": "completed", "target": "json", "model": "vera-1.0-high", "usage": { "cost": 0.0031, "inputTokens": 812, "outputTokens": 44 } } ],
    "total": 1
  }
}

Error codes

These come back on the request itself, with the HTTP status shown.

A job that ends failed. Once a job is created, a failure does not come back as an error_code. The job's status turns failed, the webhook (if any) gets { "status": "error", "job_id": "..." }, and the hold is refunded in full, so a failure costs nothing. Jobs are retried before they are marked failed. If the same document keeps failing, send a smaller document or ask for fewer fields.

Rate limits

Limits apply per API key and per endpoint. Each endpoint has a short and a long window, and you must stay under both.

Over a limit you get 429 rate_limit_exceeded with these headers:

To wait for one job, fetch it every 2 to 3 seconds, or use a webhook and don't poll at all.