Idempotency

Retry POST /v1/extract safely with the Idempotency-Key header: a duplicate request within 24 hours returns the cached response, marked cached: true, free.

Pass an Idempotency-Key header on POST requests to safely retry without creating duplicate work. If a request with the same key has already been processed, the API returns the cached response, marked with cached: true in the body.

Most integrations use idempotency keys when calling POST /v1/extract to guard against network timeouts or duplicate submissions. A typical workflow is to generate a UUID per logical operation, attach it as the Idempotency-Key header, and retry the same request on failure without risk of double-processing.

The cached response is guaranteed for 24 hours and is scoped to your organization, not to the individual API key: any key in the same workspace replaying the idempotency key gets the same cached result, while the same key string used by a different organization is treated independently. A duplicate request within the window returns the original result immediately, with no additional credit cost. Do not rely on reusing a key after the 24-hour window — mint a fresh key per logical operation instead.

A cached replay is a reduced response: it carries extraction_id, the original request_id, status, a slim document object, the extracted data, and cached: true — the confidence and processing blocks of the original response are not replayed. Document visibility is re-checked on every replay: if a Sources IAM rule has since hidden the underlying document from the calling key, the replay returns the same 404 document_not_found a fresh request would, rather than leaking the cached content.

Idempotency covers the retry side of resilient pipelines; for the delivery side, configure a webhook destination and listen for extraction.complete events instead of polling. Note that reusing a key with different request parameters will still return the first request's cached result — always generate a fresh key for each distinct operation.

Behavior

• First request — processed normally. The response and extraction ID are cached against the key.
• Duplicate request (same key within 24h) — returns the cached response immediately with HTTP 200 and cached: true. No new extraction is created and no credits are consumed.
• After the 24h window — treated as a new request.

{
  "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
  "request_id": "req_x7y8z9a0b1c2d3e4",
  "status": "complete",
  "document": {
    "id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
    "filename": "invoice.pdf",
    "type_detected": "Invoice"
  },
  "data": {
    "vendor_name": "Acme GmbH",
    "total_amount": 14250.00
  },
  "cached": true
}

# Generate a unique key per logical operation
IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F "file=@invoice.pdf" \
  -F 'schema={"vendor_name":"string","total_amount":"number"}'

# Safe to retry on network timeout — same key returns cached result
curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F "file=@invoice.pdf" \
  -F 'schema={"vendor_name":"string","total_amount":"number"}'