For developers

Ingest once, query forever.

Three modes, one API. Extract everything in a document, extract exactly the shape you send, or skip the document and query what you read last month.

Get a free API key Read the docs

bash

curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf"

5,000 credits a month free. No credit card.

Extract everything. Send a document, get every field with confidence and provenance. No schema needed.

Extract your shape. Send a JSON Schema, get exactly that back, validated, with confidence per field.

Ask the database. Typed rows with no model call, or a cited answer, over everything you have already read.

01 · Extract

Mode 1: extract everything.

Use it when you do not yet know what is in the document. Every field comes back with its confidence and the region it came from.

One call: POST /v1/extract, synchronous or asynchronous.
Every value sourced: page, region, confidence and the phase that filled it.
Registry hits are free: cells resolved from the database cost zero credits.

02 · Your schema

Mode 2: extract exactly what you asked for.

Use it when your code already knows the shape it needs, which is every time an agent calls a function.

Three formats: full JSON Schema, simplified fields (recommended) or a flat key-type map.
Validated: required fields, types and constraints are checked before you get the result.
Confidence per field, so your code decides what to trust.

Schema formats →

typescript

const result = await client.extract({
  file_path: "invoice.pdf",
  schema: {
    type: "object",
    properties: {
      vendor: { type: "string" },
      total_eur: { type: "number" },
      due_date: { type: "string", format: "date" }
    },
    required: ["vendor", "total_eur"]
  }
});
// result.data → { vendor: "Acme Corp", total_eur: 1500, ... }

03 · Query

Mode 3: skip the document, ask the database.

The documents were read days or months ago. The answer is already in your data: get it as rows or as a cited answer.

POST /v1/documents/filter: typed rows over field values. No model call, no credits.
POST /v1/ask: a plain-language question, answered with rows, the SQL behind them and a source span per claim.
Scope: limit any question to a pipeline, a spec or a set of documents.

http

POST /v1/ask
{
  "question": "Which contracts renew in the next 30 days?",
  "scope": { "pipeline_id": "pipe_contracts_2026" }
}

04 · Auth

Authentication.

Bearer keys, scoped and revocable. Create one key per integration so each can be rotated on its own.

Keys: tlnc_ prefix, passed as Authorization: Bearer, hashed at rest and shown once.
Scopes: a call outside a key’s scope returns 403 with reason insufficient_scope and the scope it needed.
Idempotency: send an Idempotency-Key on writes and a retry never creates a duplicate.

Authentication →Idempotency →

bash

curl https://api.talonic.com/v1/documents \
  -H "Authorization: Bearer tlnc_..." \
  -H "Idempotency-Key: 7f3c..."

05 · Cost

Cost on every call.

Agents can budget before they run. Every synchronous extraction returns its cost in the response headers.

Per call: credits spent, euros, remaining balance, and how many cells came free from the database.
Balance: one endpoint returns balance, 30-day burn and runway in days.
Auto top-up, human-gated: a person enables it; only then can an agent top up.

http

HTTP/1.1 200 OK
X-Talonic-Cost-Credits: 70
X-Talonic-Cost-EUR: 0.07
X-Talonic-Balance-Credits: 64930
X-Talonic-Cells-Resolved-Registry: 0
X-Talonic-Cells-Resolved-AI: 1

06 · Errors

Errors you can branch on.

Every error has the same envelope. Branch on reason when it is present, then on code. Retry only what says it is retryable.

Stable tokens: UPPER_SNAKE codes, plus a lowercase reason for refusals.
Retry safely: the retryable flag, exponential backoff, and an Idempotency-Key on work-creating calls.
Support-ready: every error carries a request_id.

Error reference →

json

{
  "statusCode": 403,
  "code": "INSUFFICIENT_PERMISSIONS",
  "reason": "insufficient_scope",
  "retryable": false,
  "request_id": "b6f1c2e0-..."
}

07 · Webhooks

Webhooks and delivery.

Async extractions and delivery events fire signed webhooks. Or skip the webhook and deliver straight into storage and business apps.

Signed: HMAC-SHA256, with signature, idempotency key, attempt and event id in the headers.
Retried: seven attempts over about ten hours, overridable per binding.
Replayable: terminal failures land in a dead-letter queue you can replay.
Destinations: SFTP, S3, Azure Blob, Google Drive, Google Sheets, OneDrive, SharePoint, Gmail, Outlook.

Webhooks reference →

08 · SDK & MCP

Node SDK and MCP server.

Thin wrappers around the same REST API. For any other language, generate a client from the OpenAPI spec.

Node SDK: npm install @talonic/node.
MCP server: hosted at mcp.talonic.com, nothing to install. On Claude.ai it signs in with OAuth, no key in the config.
Tools for agents: extract, OCR to Markdown, search, filter by field, get a document, schemas, and balance and usage so an agent can budget.
In production, pin a version so a release cannot change a tool your agent depends on.

SDK docs →MCP docs →OpenAPI spec →

json

{
  "mcpServers": {
    "talonic": {
      "url": "https://mcp.talonic.com/mcp",
      "headers": { "Authorization": "Bearer tlnc_..." }
    }
  }
}

bash

npm install @talonic/node

09 · Limits

Limits and metering.

Usage is metered in credits, not request quotas. 1,000 credits are one euro at every pack size.

Per operation: 100 credits per page read, 20 per AI-resolved cell, 0 per cell from the database. Batch mode runs at half price.
Daily request limits per tier and endpoint family. A 429 says when the counter resets.
File size: 20 MB on Free, 100 MB on Pro, 500 MB on Enterprise.

Rate limits →

Free5,000 credits a monthNo credit card. A hard cap until the monthly reset or a top-up.Get a key →Pay as you goPacks from €10Flat rate at every size, bought in the app. Credits keep for twelve months.See pricing →EnterpriseVolume contractsInvoicing, custom quotas and unlimited daily requests.Talk to us →

10 · Formats

25+ formats in.

Documents, images, text and archives. German, English, French and Spanish at production quality.

DocumentsPDF and OfficePDF, DOCX, DOC, XLSX, XLS, XLSM, PPTX, PPT

ImagesScans and photosPNG, JPG, JPEG, GIF, WEBP, BMP

Text and archivesPlain, mail, dataTXT, MD, HTML, JSON, CSV, XML, EML, MSG, ZIP

11 · Why not RAG

Why not just RAG?

Because the second question should be free, and the same question tomorrow should return the same answer. Three published benchmarks, losses included.

Accuracy5 of 5 vs 0 of 528 SEC 10-K filings, preregistered, XBRL gold labels. Retrieval answered none of the headline ranking queries.Read the benchmark →Cost$0 per 1,000 queries$10.14 once for 53 documents, then nothing per question. Retrieval pays on every one.Read the cost benchmark →ConsistencyByte-identical, ten runsSame 100 questions, ten passes. Hybrid RAG matched itself on 2 of 39.Read the consistency benchmark →

12 · Resources

Resources.

Everything you need to build, in one place.

QuickstartYour first extraction in five minutes.talonic.com/docs/quickstart API referenceEvery endpoint with request and response.talonic.com/docs/api OpenAPI specGenerate a client in any language.talonic.com/openapi.json MCP RegistryThe official listing of the Talonic MCP server.io.github.talonicdev/talonic-mcp GitHubNode SDK and MCP server source.github.com/talonicdev llms.txtThe site, readable by your coding agent.talonic.com/llms.txt

Ship your first call today.

Get API keys

Get a free API key

Technical deep dive

30 minutes with an implementation specialist or senior engineer on your integration.

Book a session