FOR DEVELOPERS

Three modes. One API.

Auto-detect what's in the document. Send your own JSON Schema and get exactly that shape. Or skip the document entirely and query data you already ingested. Pick the mode that matches the call you're already writing.

Read the docs →

01 THREE MODES

One endpoint. Three contracts.

MODE 1

Extract everything

Send a document, get every field the AI discovers. No schema needed.

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

Use when you don't yet know what's in the document, or you're prototyping and want to see what's there.

MODE 2

Extract exactly what you asked for

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

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" },
      line_items: {
        type: "array",
        items: {
          type: "object",
          properties: {
            description: { type: "string" },
            amount_eur: { type: "number" }
          }
        }
      }
    },
    required: ["vendor", "total_eur"]
  }
});
// result.data == { vendor: "Acme Corp", total_eur: 1500.00, ... }
// Every field includes confidence and provenance.

Three schema formats accepted →

JSON Schema (most control)

{"type": "object", "properties": { ... }}

Simplified fields (recommended)

{"fields": [
  {"name": "vendor", "type": "string", "description": "..."}
]}

Flat key-type map (quickest)

{"vendor": "string", "total": "number"}

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

MODE 3

Skip the document, ask the question

Documents were ingested days or months ago. Now just ask.

const results = await client.documents.filter({
  conditions: [
    { fieldId: "vendor_name", operator: "eq", value: "Meridian Energy AG" },
    { fieldId: "contract_year", operator: "eq", value: "2026" }
  ],
  limit: 50
});
// Returns { data: [...], total: N }
// Zero re-extraction. Zero AI calls.

Use when the answer is already in your data. "Ingest once, query forever" as an actual API endpoint — not a slogan.

Same auth, same response shape, same provenance. Pick the mode that fits the call you're writing.

02 AUTHENTICATION

Authentication

API keys are prefixed tlnc_ and passed as Authorization: Bearer on every request. Keys are SHA-256 hashed at rest — the full value is shown exactly once, at creation.

Four scopes: extract, read, write, billing. Default keys get extract, read, and write. The billing scope is opt-in.

Authorization: Bearer $TALONIC_API_KEY

API keys carry a tlnc_ prefix.

All write endpoints honor Idempotency-Key headers. Send the same key twice, get the same response — no duplicate resources.

Manage keys in the dashboard →

03 COST & BILLING

The agent billing story.

Read the cost on every call

Every synchronous /v1/extract response includes cost headers. Agents track spending per call without a separate API request.

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

Headers appear on synchronous 200 responses. Async 202 poll responses don't include them.

Check balance and runway

A single endpoint returns current balance, 30-day burn rate, and projected runway in days.

GET /v1/credits/balance

{
  "balance_credits": 64930,
  "balance_eur": 64.93,
  "burn_rate_30d_credits": 12400,
  "projected_runway_days": 157,
  "tier": "pro",
  "tier_resets_at": "2026-05-01T00:00:00Z"
}

Auto top-up (human-gated)

A human enables auto top-up via PATCH /v1/billing/settings with auto_topup_enabled: true, an auto_topup_threshold, and an auto_topup_amount.

Once enabled, agents call POST /v1/billing/topup with the billing scope. The endpoint returns 403 if auto top-up isn't enabled — agents cannot enable it themselves. When the balance is above threshold, the endpoint returns { "topped_up": false } without adding credits.

04 ERRORS & RETRIES

Errors and retries

See the error reference for all error codes, the response envelope, retry guidance, and backoff recommendations.

05 WEBHOOKS

Webhooks

Async extractions and delivery events fire HMAC-SHA256 signed webhooks. Failed deliveries retry with exponential backoff (1min, 5min, 30min, 4hr). Every payload includes an idempotency key for safe deduplication.

See the webhooks reference for event names, signing verification snippets, and the retry policy.

06 SDKS & MCP

SDKs and MCP

NODE SDK

npm install @talonic/node

import { Talonic } from "@talonic/node";

const client = new Talonic({
  apiKey: process.env.TALONIC_API_KEY!
});

GitHub →

MCP SERVER

Hosted — zero install, works everywhere:

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

Or run locally via npx:

{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": ["-y", "@talonic/mcp@latest"],
      "env": {
        "TALONIC_API_KEY": "tlnc_live_..."
      }
    }
  }
}

GitHub →

MCP docs →

The Node SDK and MCP server are thin wrappers around the same REST API. For other languages, the API works directly — see the OpenAPI spec or jump to Mode 1 above.

07 RATE LIMITS

Rate limits

Free: 50 extractions per day
Pro: 2,000 extractions per day
Enterprise: Unlimited, custom rate

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When the limit is hit, the API returns 429. Use X-RateLimit-Reset to determine when to retry.

08 SUPPORTED FORMATS

Supported formats

25+ formats supported across documents, images, text, and archives.

Documents: PDF, DOCX, DOC, XLSX, XLS, XLSM, PPTX, PPT

Images: PNG, JPG, JPEG, GIF, WEBP, BMP

Text: TXT, MD, HTML, JSON, CSV, XML, EML, MSG

Archives: ZIP

09 RESOURCES

Resources

OpenAPI spec: talonic.com/openapi.json
Documentation: talonic.com/docs
Pricing: talonic.com/pricing
GitHub: github.com/talonicdev
Support: info@talonic.ai