Quick Start

Get started with the Talonic API in minutes: auto-detect extraction, schema-driven extraction, and querying ingested documents, with cost headers on every call.

This quick start shows the three ways to use the Talonic document extraction API: send a document with no schema and auto-detect every field, send a document with a schema and get exactly that shape back, or query data you already ingested without re-processing. Every call returns per-field confidence scores and cost transparency headers.

Prerequisites

A Talonic account — sign up at [app.talonic.com](https://app.talonic.com)
An API key from Settings → API Keys (starts with tlnc_)
A PDF or image file to extract (e.g. an invoice)

Set your API key

Mode 1 — Auto-detect extract

Send a document with no schema. Talonic discovers every field automatically.

curl — auto-detect all fields

Returns every field the AI discovers — vendor, dates, amounts, line items, addresses — with per-field confidence scores. Use this when you don't know the document structure upfront.

Mode 2 — Schema-driven extract

Send a document AND the shape you want. Get exactly those fields back.

curl — extract with inline schema

The response contains exactly the four fields you asked for — nothing more. Save the schema with POST /v1/schemas for reuse across future extractions.

Mode 3 — Query ingested data

Don't send a document. Query data you already extracted — across all documents in your workspace.

curl — filter previously extracted documents

Returns all documents matching your filter — no re-extraction, no AI cost. Ingest once, query forever.

Ask your first question

Once documents are ingested, you can skip filters and schemas entirely and just ask. POST /v1/ask runs a read-only agent turn over your whole corpus and returns a markdown answer with a citation for every claim, plus a verification verdict. Submit the question, then poll the returned poll_url about every 2 seconds; answers take 10 to 60 seconds. One question costs a flat 100 credits (0.10 EUR).

curl: ask a question, then poll for the answer

On deployments where self-serve signup is enabled, you do not even need a dashboard to reach this point: POST /v1/auth/register with your email sends a magic link, and confirming it returns a scoped tlnc_ API key plus a seeded workspace with two example documents (a Northwind invoice and an Acme/Globex master services agreement), so your first POST /v1/ask works within a minute of registering. See [Ask Your Documents](post-ask) for the full contract.

Documents of 5 pages or fewer return synchronously (200 with data). Larger documents return 202 Accepted with a poll_url — poll GET /v1/documents/:id until status is completed, then fetch results from GET /v1/documents/:id/extractions. See [Processing Modes](extract-processing-mode).

Cost on every call

Every synchronous extraction response includes cost headers so you can track spend per call:

Cost headers

Fields resolved from the registry (X-Talonic-Cells-Resolved-Registry) cost nothing. Only AI-resolved fields consume credits.

Example response

A synchronous extraction returns structured data with confidence scores:

Response (200 OK)

Next steps

Ask your documents: one flat-priced question over the whole corpus with cited, verified answers via POST /v1/ask. See [Ask Your Documents](post-ask).
Reuse schemas — save your schema with POST /v1/schemas, then pass schema_id on future extractions.
Large documents — files >5 pages return 202 Accepted with a poll_url. See [Processing Modes](extract-processing-mode).
Webhooks — receive results via extraction.complete events instead of polling. See [Webhook Events](webhook-events).
Batch mode — process at 50% cost with processing_mode=batch. See [Batches](batches).
Credits — check your balance anytime with GET /v1/credits/balance. See [Credits](credits-balance).