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)

export TALONIC_API_KEY="tlnc_live_..."

Mode 1 — Auto-detect extract

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

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

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 -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf" \
  -F 'schema={"vendor_name":"string","invoice_number":"string","total_amount":"number","due_date":"date"}'

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 -X POST https://api.talonic.com/v1/documents/filter \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "fieldId": "vendor_name", "operator": "eq", "value": "Acme GmbH" }
    ],
    "limit": 50
  }'

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).

ASK_ID=$(curl -s -X POST https://api.talonic.com/v1/ask \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Which vendors invoiced us more than once, and for how much in total?"}' \
  | jq -r '.ask_id')

curl -s https://api.talonic.com/v1/ask/$ASK_ID \
  -H "Authorization: Bearer $TALONIC_API_KEY"

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.

Cost on every call

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

X-Talonic-Cost-Credits: 12
X-Talonic-Cost-EUR: 0.01
X-Talonic-Balance-Credits: 64918
X-Talonic-Cells-Resolved-Registry: 3
X-Talonic-Cells-Resolved-AI: 5

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:

{
  "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
  "request_id": "req_x7y8z9a0b1c2d3e4",
  "status": "complete",
  "document": {
    "id": "f0e1d2c3-b4a5-9687-8765-432109876543",
    "filename": "invoice.pdf",
    "pages": 2,
    "type_detected": "Invoice"
  },
  "data": {
    "vendor_name": "Acme GmbH",
    "invoice_number": "INV-2025-0042",
    "total_amount": 14250.00,
    "due_date": "2025-04-15"
  },
  "confidence": {
    "overall": 0.96,
    "fields": {
      "vendor_name": 0.97,
      "invoice_number": 0.99,
      "total_amount": 0.94,
      "due_date": 0.99
    }
  },
  "processing": {
    "duration_ms": 1840,
    "pages_processed": 2
  }
}

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).