FÜR ENTWICKLER

Einmal einlesen, für immer abfragen.

Drei Modi. Eine API. Automatische Erkennung dessen, was im Dokument steht. Senden Sie Ihr eigenes JSON Schema und erhalten Sie genau diese Struktur. Oder überspringen Sie das Dokument ganz und fragen Sie bereits eingelesene Daten ab. Wählen Sie den Modus, der zu dem Aufruf passt, den Sie bereits schreiben.

Kostenlos starten, API-Schlüssel erhalten →Dokumentation lesen →

01 DREI MODI

Ein Endpoint. Drei Contracts.

MODUS 1

Alles extrahieren

Senden Sie ein Dokument und erhalten Sie jedes Feld, das die KI erkennt. Kein Schema erforderlich.

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

Nutzen Sie dies, wenn Sie noch nicht wissen, was im Dokument steht, oder wenn Sie prototypisch testen und sehen möchten, was enthalten ist.

MODUS 2

Extrahieren Sie genau das, was Sie angefragt haben

Senden Sie ein Dokument UND die gewünschte Struktur. Erhalten Sie genau diese Struktur zurück.

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.

Drei Schema-Formate werden akzeptiert →

JSON Schema (meiste Kontrolle)

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

Vereinfachte Felder (empfohlen)

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

Flache Key-Type-Map (am schnellsten)

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

Verwenden Sie dies, wenn Ihr Code die benötigte Struktur bereits kennt: das ist jedes Mal der Fall, wenn ein Agent eine Funktion aufruft.

MODUS 3

Dokument überspringen, Frage stellen

Dokumente wurden vor Tagen oder Monaten erfasst. Jetzt einfach fragen.

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.

Verwenden Sie dies, wenn die Antwort bereits in Ihren Daten vorhanden ist. „Einmal erfassen, für immer abfragen" als echter API-Endpunkt, nicht als Slogan.

Gleiche Authentifizierung, gleiche Antwortstruktur, gleiche Herkunftsnachweise. Wählen Sie den Modus, der zum Aufruf passt, den Sie schreiben.

02 AUTHENTIFIZIERUNG

Authentifizierung

API-Schlüssel tragen das Präfix tlnc_ und werden als Authorization: Bearer bei jeder Anfrage übergeben. Schlüssel werden im Ruhezustand mit SHA-256 gehasht, der vollständige Wert wird nur einmal bei der Erstellung angezeigt.

Vier Scopes: extract, read, write, billing. Standardschlüssel erhalten extract, read und write. Der billing Scope ist Opt-in.

Authorization: Bearer $TALONIC_API_KEY

API-Schlüssel tragen ein tlnc_-Präfix.

Alle Schreib-Endpunkte berücksichtigen Idempotency-Key-Header. Senden Sie denselben Schlüssel zweimal, erhalten Sie dieselbe Antwort, keine doppelten Ressourcen.

Schlüssel im Dashboard verwalten →

03 KOSTEN & ABRECHNUNG

Die Abrechnungsgeschichte für Agenten.

Kosten bei jedem Aufruf ablesen

Jede synchrone /v1/extract Antwort enthält Kosten-Header. Agenten verfolgen die Ausgaben pro Aufruf, ohne eine separate API-Anfrage zu stellen.

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

Header erscheinen bei synchronen 200-Antworten. Asynchrone 202-Poll-Antworten enthalten sie nicht.

Guthaben und Reichweite prüfen

Ein einzelner Endpoint liefert aktuelles Guthaben, die 30-Tage-Burn-Rate und die geschätzte Reichweite in Tagen.

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"
}

Automatisches Aufladen (mit menschlicher Freigabe)

Ein Mensch aktiviert das automatische Aufladen über PATCH /v1/billing/settings mit auto_topup_enabled: true, einem auto_topup_threshold und einem auto_topup_amount.

Sobald aktiviert, rufen Agenten POST /v1/billing/topup mit dem billing Scope auf. Der Endpoint gibt 403 zurück, wenn das automatische Aufladen nicht aktiviert ist. Agenten können es nicht selbst aktivieren. Liegt das Guthaben über dem Schwellenwert, gibt der Endpoint { "topped_up": false } zurück, ohne Guthaben hinzuzufügen.

04 FEHLER & WIEDERHOLUNGEN

Fehler und Wiederholungen

Siehe die Fehlerreferenz für alle Fehlercodes, den Antwort-Envelope, Hinweise zu Wiederholungen und Empfehlungen zum Backoff.

05 WEBHOOKS

Webhooks

Asynchrone Extraktionen und Zustellungsereignisse lösen HMAC-SHA256-signierte Webhooks aus. Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff wiederholt (1 Min., 5 Min., 30 Min., 4 Std.). Jede Payload enthält einen Idempotenzschlüssel für sichere Deduplizierung.

Siehe die Webhooks-Referenz für Event-Namen, Codebeispiele zur Signaturprüfung und die Wiederholungsrichtlinie.

06 SDKS & MCP

SDKs und 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

Gehostet: keine Installation nötig, funktioniert überall:

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

Oder lokal ausführen via npx:

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

GitHub →

MCP-Dokumentation →

Das Node SDK und der MCP-Server sind schlanke Wrapper um dieselbe REST-API. Für andere Sprachen funktioniert die API direkt: siehe die OpenAPI-Spezifikation oder direkt zu Mode 1 oben.

07 RATENLIMITS

Ratenlimits

Kostenlos: 5,000 credits/month, keine Kreditkarte (harte Obergrenze)
Pro: 2.000 Extraktionen pro Tag
Enterprise: Unbegrenzt, individuelle Rate

Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining, und X-RateLimit-Reset. Wird das Limit erreicht, gibt die API 429 zurück. Verwenden Sie X-RateLimit-Reset, um zu bestimmen, wann ein erneuter Versuch erfolgen soll.

08 UNTERSTÜTZTE FORMATE

Unterstützte Formate

Über 25 Formate für Dokumente, Bilder, Text und Archive unterstützt.

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

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

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

Archive: ZIP

09 RESSOURCEN

Ressourcen

OpenAPI-Spezifikation: talonic.com/openapi.json
Dokumentation: talonic.com/docs
Datenextraktions-API: talonic.com/data-extraction-api
Preise: talonic.com/pricing
GitHub: github.com/talonicdev
Support: info@talonic.ai