Base URL

All Talonic API endpoints are relative to https://api.talonic.com/v1 over HTTPS. JSON bodies by default, multipart for uploads, versioned under the v1 prefix.

The Talonic API base URL is https://api.talonic.com/v1. All endpoints are relative to this base, all requests must use HTTPS, and all paths in this reference assume the /v1 prefix. Most integrations set the base as a constant in their HTTP client configuration, so a typical request URL looks like https://api.talonic.com/v1/extract or https://api.talonic.com/v1/documents.

https://api.talonic.com/v1

The API uses standard JSON request and response bodies with Content-Type: application/json, except for file uploads, which use multipart/form-data. Errors follow one consistent envelope: a JSON body carrying a machine-readable error (or code) plus a human-readable message, under the standard HTTP status — 400 for validation failures, 401 for a missing or invalid key, 402 for insufficient credits, 404 for a resource outside your workspace, 429 for rate limits.

Standard response headers

Every response carries a set of standard headers. X-Request-Id uniquely identifies the request for tracing and support. X-Processing-Region names the region that served the call (e.g. eu-west), which matters for data-residency review. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset report your tier's daily quota for the endpoint's namespace, what is left of it, and when the counter resets — read them to self-meter instead of probing for 429s.

curl -si https://api.talonic.com/v1/documents?limit=1 \
  -H "Authorization: Bearer tlnc_your_api_key" | head -12

HTTP/1.1 200 OK
X-Request-Id: req_0be8f705e0a74221
X-Processing-Region: eu-west
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1809
X-RateLimit-Reset: 2026-08-30T00:00:00.000Z
Content-Type: application/json; charset=utf-8

Synchronous extraction responses add the cost family on top: X-Talonic-Cost-Credits, X-Talonic-Cost-EUR, and X-Talonic-Balance-Credits report what the call cost and what remains, and X-Talonic-Cells-Resolved-Registry / X-Talonic-Cells-Resolved-AI break down how many fields were resolved for free from the field registry versus by AI. Log these alongside your own request ids and you have per-call spend attribution without a billing export.

Error envelope

Handle errors by reading the machine-readable code, never by parsing the message text — messages can be reworded, codes are stable. The same envelope shape is used across all endpoints, so one error handler covers the whole API. Retry guidance follows the status: 429 and 503 are retryable after a pause, 4xx validation errors are not (fix the request), and 402 means top up credits and resubmit unchanged.

{
  "error": "insufficient_credits",
  "message": "Credit balance too low for this operation. Top up and retry."
}

Versioning

There is no versioning in the URL beyond /v1. Breaking changes will be communicated in advance and introduced under a new version prefix. Non-breaking additions — new response fields, new endpoints, new optional parameters — ship continuously under /v1, so parse responses tolerantly: ignore fields you do not recognize rather than validating against a closed shape.