Veralens

DocsAPI 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://api.veralens.ai/v1

Authentication

Programmatic requests authenticate with an API key as a Bearer token. Create keys under 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; treat human-readable text as advisory only.

POST /jobs/create

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

Body

Field	Type	Required	Description
`sources`	array	yes	One or more inputs. Each is `{ "type": "text" \| "image", "data": string }`. Text `data` is raw text; image `data` is a data URL (`data:image/png;base64,...`). Raster images only — SVG and other vector formats are rejected.
`schema`	object	conditional	A JSON Schema describing the output object. When present, `target` must be `json` (or omitted).
`target`	string	conditional	Output format: `json`, `markdown`, or `plaintext`. Required when no `schema` is given. Defaults to `json` when a schema is present.
`global_prompt`	string	no	Natural-language instructions applied to the whole extraction.
`engine`	string	no	`vera-1.0-high` (default) or `vera-1.0-low`. See Pricing.
`webhook_url`	string	no	HTTPS URL to receive the result. API-key auth only. See Jobs & Queue.

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

Response — 201 Created. Returns the full job object (same shape as GET /jobs/:jobId/get below), already in pending. model, target, and the precharge 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://api.veralens.ai/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

Field	Type	Description
`id`	string	Job id.
`status`	string	`pending`, `completed`, or `failed`.
`createdAt`	string	ISO timestamp the job was created.
`source`	string	Origin: `key` (API) or `playground` (dashboard).
`target`	string	`json`, `markdown`, or `plaintext`.
`sources`	object	Count of inputs by type: `images`, `texts`, `documents`.
`model`	string	Engine used, or `null` before it runs.
`usage`	object	Billed `cost` (USD), `inputTokens`, `outputTokens`. `null` values until settled.
`output`	string	The extraction result as a string. For `json` targets, `JSON.parse` it. `null` until completed.
`durationMs`	number	Wall-clock runtime; `null` while `pending`.

GET /jobs/list

List your jobs, most recent first.

Query parameters

Param	Type	Default	Description
`q`	string	—	Free-text search over jobs.
`status`	string	`all`	`all`, `finished`, `pending`, or `failed`.
`source`	string	—	Filter by origin: `key` or `playground`.
`limit`	number	`100`	Page size, 1–500.
`offset`	number	`0`	Rows to skip.

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

`error_code`	HTTP	Meaning
`unauthorized`	401	Missing or invalid API key.
`invalid_input`	400	The request body failed validation.
`insufficient_balance`	400	Not enough balance to cover the job's hold. Add funds.
`job_not_found`	404	No job with that id for your account.
`job_image_mime_unsupported`	400	An image source used an unsupported format (e.g. SVG). Use PNG, JPEG, or WebP.
`rate_limit_exceeded`	429	Too many requests — back off and retry.
`inference_timeout`	504	The model timed out. Retry with a smaller payload.
`inference_rate_limited`	429	Inference is throttled — retry shortly.
`parsing_failed`	500	The model response could not be parsed. Retry.
`internal_server_error`	500	Unexpected error. Retry.

Rate limits

Every endpoint is rate limited per route. When you exceed a limit you get 429 with rate_limit_exceeded; retry with exponential backoff.