@talonic/docs 0.14.0 → 0.16.0

package/dist/seo.js

@@ -4,7 +4,7 @@ var openapi_default = {
   info: {
     title: "Talonic API",
     version: "1.0.0",
-    description: 'Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (\u22645 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` \u2014 poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {"async": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` \u2014 daily cap for the namespace\n- `X-RateLimit-Remaining` \u2014 requests left today\n- `X-RateLimit-Reset` \u2014 ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1\u2013100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  "statusCode": 400,\n  "code": "VALIDATION_ERROR",\n  "error": "Bad Request",\n  "message": "name is required.",\n  "retryable": false,\n  "timestamp": "2026-04-25T14:30:00.000Z",\n  "path": "/v1/schemas"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Flow\n\nDocuments \u22645 pages return results synchronously (`200`). Larger documents\n\u2014 or any request with `options: {"async": true}` \u2014 return `202 Accepted`.\n\n**1. Submit extraction:**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H "Authorization: Bearer tlnc_live_abc123" \\\n  -F "file=@contract.pdf" \\\n  -F \'options={"async": true}\'\n```\n\nResponse `202`:\n```json\n{\n  "request_id": "req_x7y8z9a0",\n  "status": "processing",\n  "document": { "id": "f0e1d2c3-b4a5-9687-8765-432109876543" },\n  "poll_url": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543"\n}\n```\n\n**2. Poll until complete:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543 \\\n  -H "Authorization: Bearer tlnc_live_abc123"\n```\n\nWhile processing: `{ "status": "processing" }`\nWhen done: `{ "status": "completed" }`\n\n**3. Retrieve results:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543/extractions \\\n  -H "Authorization: Bearer tlnc_live_abc123"\n```\n\n**Python \u2014 complete async flow with exponential backoff:**\n\n```python\nimport time\nimport requests\n\nAPI_KEY = "tlnc_live_..."\nBASE = "https://api.talonic.com/v1"\nHEADERS = {"Authorization": f"Bearer {API_KEY}"}\n\n# Step 1: Submit async extraction\nresp = requests.post(f"{BASE}/extract",\n    headers=HEADERS,\n    files={"file": open("contract.pdf", "rb")},\n    data={"options": \'{"async": true}\'})\ndoc_id = resp.json()["document"]["id"]\n\n# Step 2: Poll with exponential backoff (2s \u2192 4s \u2192 8s \u2192 16s \u2192 30s cap)\ndelay = 2\nfor _ in range(20):\n    time.sleep(delay)\n    doc = requests.get(f"{BASE}/documents/{doc_id}", headers=HEADERS).json()\n    if doc["status"] == "completed":\n        break\n    if doc["status"] == "error":\n        raise Exception(f"Extraction failed: {doc.get(\'error\')}")\n    delay = min(delay * 2, 30)\n\n# Step 3: Retrieve extracted data\nextractions = requests.get(\n    f"{BASE}/documents/{doc_id}/extractions", headers=HEADERS).json()\ndata = extractions["data"][0]["data"]\nconfidence = extractions["data"][0]["confidence"]["overall"]\nprint(f"Extracted {len(data)} fields (confidence: {confidence})")\nprint(data)\n# \u2192 {"vendor_name": "Acme Corp", "total_amount": 1250.00, ...}\n```\n\n**TypeScript \u2014 same flow:**\n\n```typescript\nconst API_KEY = "tlnc_live_...";\nconst BASE = "https://api.talonic.com/v1";\nconst headers = { Authorization: `Bearer ${API_KEY}` };\n\n// Step 1: Submit async extraction\nconst form = new FormData();\nform.append("file", fs.createReadStream("contract.pdf"));\nform.append("options", \'{"async": true}\');\nconst { document } = await fetch(`${BASE}/extract`, {\n  method: "POST", headers, body: form,\n}).then((r) => r.json());\n\n// Step 2: Poll with exponential backoff\nlet delay = 2000;\nlet doc: any;\nfor (let i = 0; i < 20; i++) {\n  await new Promise((r) => setTimeout(r, delay));\n  doc = await fetch(`${BASE}/documents/${document.id}`, { headers }).then((r) => r.json());\n  if (doc.status === "completed") break;\n  if (doc.status === "error") throw new Error(`Extraction failed: ${doc.error}`);\n  delay = Math.min(delay * 2, 30_000);\n}\n\n// Step 3: Retrieve extracted data\nconst { data: extractions } = await fetch(\n  `${BASE}/documents/${document.id}/extractions`, { headers }\n).then((r) => r.json());\nconsole.log(extractions[0].data);\n// \u2192 { vendor_name: "Acme Corp", total_amount: 1250.00, ... }\n```\n\nRecommended polling: 2s initial, exponential backoff (2\u21924\u21928\u219216\u219230s cap),\ntimeout after 5 minutes.\n\n**Alternative \u2014 Webhooks:** Configure a delivery destination and listen for\n`document.extracted` events. See the Delivery tag.\n\n**Job status state machine:**\n`pending` \u2192 `queued` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Performance\n\n| Document size | Expected latency | Max timeout |\n|---------------|------------------|-------------|\n| 1\u20135 pages     | Sync, <3s        | 30s         |\n| 6\u201350 pages    | <30s average     | 5 min       |\n| 50+ pages     | <5 min average   | 30 min      |\n\n**Uptime SLA:** 99.5% (Build), 99.9% (Scale), custom (Enterprise).\n\n**Max file size:** 500 MB. JSON request bodies (schemas, jobs): 1 MB.\n\n**Idempotency:** Pass `Idempotency-Key` header on POST requests. Keys are\nvalid for 24 hours and scoped per API key. Duplicates return the cached\nresponse with `cached: true`.\n',
+    description: 'Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Quick Start\n\n**1. Get your API key**\n\nSign up at [app.talonic.com](https://app.talonic.com) \u2192 Settings \u2192 API Keys \u2192 Create key.\nKeys start with `tlnc_live_` (production) or `tlnc_test_` (sandbox).\nAll examples below use `tlnc_live_abc123` as a placeholder.\n\n**2. Extract your first document**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H "Authorization: Bearer tlnc_live_abc123" \\\n  -F "file=@invoice.pdf" \\\n  -F \'schema={"properties":{"vendor_name":{"type":"string"},"total_amount":{"type":"number"},"invoice_date":{"type":"string"}}}\'\n```\n\n**Python:**\n```python\nimport requests\nresp = requests.post("https://api.talonic.com/v1/extract",\n    headers={"Authorization": "Bearer tlnc_live_abc123"},\n    files={"file": open("invoice.pdf", "rb")},\n    data={"schema": \'{"properties":{"vendor_name":{"type":"string"},"total_amount":{"type":"number"},"invoice_date":{"type":"string"}}}\'})\nprint(resp.json()["data"])\n```\n\n**TypeScript:**\n```typescript\nconst form = new FormData();\nform.append("file", fs.createReadStream("invoice.pdf"));\nform.append("schema", \'{"properties":{"vendor_name":{"type":"string"},"total_amount":{"type":"number"},"invoice_date":{"type":"string"}}}\');\nconst res = await fetch("https://api.talonic.com/v1/extract", {\n  method: "POST",\n  headers: { Authorization: "Bearer tlnc_live_abc123" },\n  body: form,\n}).then(r => r.json());\nconsole.log(res.data);\n```\n\n**3. What you get back**\n\n```json\n{\n  "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",\n  "request_id": "req_x7y8z9a0b1c2d3e4",\n  "status": "complete",\n  "document": {\n    "id": "f0e1d2c3-b4a5-9687-8765-432109876543",\n    "filename": "invoice.pdf",\n    "pages": 2,\n    "size_bytes": 184320,\n    "type_detected": "Invoice",\n    "language_detected": "en"\n  },\n  "data": {\n    "vendor_name": "Acme GmbH",\n    "total_amount": 14250.00,\n    "invoice_date": "2025-03-15"\n  },\n  "confidence": {\n    "overall": 0.96,\n    "fields": {\n      "vendor_name": 0.97,\n      "total_amount": 0.94,\n      "invoice_date": 0.99\n    }\n  },\n  "processing": {\n    "duration_ms": 1840,\n    "pages_processed": 2,\n    "region": "eu-west"\n  },\n  "links": {\n    "self": "/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab",\n    "document": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543"\n  }\n}\n```\n\n- **`data`** \u2014 extracted fields as key-value pairs matching your schema.\n- **`confidence.fields`** \u2014 per-field score from 0 to 1. Above 0.9 is high confidence; below 0.7 flags for review.\n- **`extraction_id`** \u2014 use this to retrieve, correct, or deliver results later.\n- Full response schema: [ExtractSyncResponse](#/components/schemas/ExtractSyncResponse)\n\n**4. Next steps**\n\n- **50+ pages?** Use async mode \u2014 see [Async Extraction Flow](#section/Async-Extraction-Flow) below.\n- **Reusable schemas** \u2014 save field definitions with `POST /v1/schemas`, then pass `schema_id` on future extractions.\n- **Receive results via webhook** \u2014 configure a delivery destination and listen for `document.extracted` events. See the [Delivery](#tag/Delivery) tag.\n\n---\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (\u22645 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` \u2014 poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {"async": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` \u2014 daily cap for the namespace\n- `X-RateLimit-Remaining` \u2014 requests left today\n- `X-RateLimit-Reset` \u2014 ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1\u2013100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  "statusCode": 400,\n  "code": "VALIDATION_ERROR",\n  "error": "Bad Request",\n  "message": "name is required.",\n  "retryable": false,\n  "timestamp": "2026-04-25T14:30:00.000Z",\n  "path": "/v1/schemas"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Flow\n\nDocuments \u22645 pages return results synchronously (`200`). Larger documents\n\u2014 or any request with `options: {"async": true}` \u2014 return `202 Accepted`.\n\n**1. Submit extraction:**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H "Authorization: Bearer tlnc_live_abc123" \\\n  -F "file=@contract.pdf" \\\n  -F \'options={"async": true}\'\n```\n\nResponse `202`:\n```json\n{\n  "request_id": "req_x7y8z9a0",\n  "status": "processing",\n  "document": { "id": "f0e1d2c3-b4a5-9687-8765-432109876543" },\n  "poll_url": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543"\n}\n```\n\n**2. Poll until complete:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543 \\\n  -H "Authorization: Bearer tlnc_live_abc123"\n```\n\nWhile processing: `{ "status": "processing" }`\nWhen done: `{ "status": "completed" }`\n\n**3. Retrieve results:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543/extractions \\\n  -H "Authorization: Bearer tlnc_live_abc123"\n```\n\n**Python \u2014 complete async flow with exponential backoff:**\n\n```python\nimport time\nimport requests\n\nAPI_KEY = "tlnc_live_..."\nBASE = "https://api.talonic.com/v1"\nHEADERS = {"Authorization": f"Bearer {API_KEY}"}\n\n# Step 1: Submit async extraction\nresp = requests.post(f"{BASE}/extract",\n    headers=HEADERS,\n    files={"file": open("contract.pdf", "rb")},\n    data={"options": \'{"async": true}\'})\ndoc_id = resp.json()["document"]["id"]\n\n# Step 2: Poll with exponential backoff (2s \u2192 4s \u2192 8s \u2192 16s \u2192 30s cap)\ndelay = 2\nfor _ in range(20):\n    time.sleep(delay)\n    doc = requests.get(f"{BASE}/documents/{doc_id}", headers=HEADERS).json()\n    if doc["status"] == "completed":\n        break\n    if doc["status"] == "error":\n        raise Exception(f"Extraction failed: {doc.get(\'error\')}")\n    delay = min(delay * 2, 30)\n\n# Step 3: Retrieve extracted data\nextractions = requests.get(\n    f"{BASE}/documents/{doc_id}/extractions", headers=HEADERS).json()\ndata = extractions["data"][0]["data"]\nconfidence = extractions["data"][0]["confidence"]["overall"]\nprint(f"Extracted {len(data)} fields (confidence: {confidence})")\nprint(data)\n# \u2192 {"vendor_name": "Acme Corp", "total_amount": 1250.00, ...}\n```\n\n**TypeScript \u2014 same flow:**\n\n```typescript\nconst API_KEY = "tlnc_live_...";\nconst BASE = "https://api.talonic.com/v1";\nconst headers = { Authorization: `Bearer ${API_KEY}` };\n\n// Step 1: Submit async extraction\nconst form = new FormData();\nform.append("file", fs.createReadStream("contract.pdf"));\nform.append("options", \'{"async": true}\');\nconst { document } = await fetch(`${BASE}/extract`, {\n  method: "POST", headers, body: form,\n}).then((r) => r.json());\n\n// Step 2: Poll with exponential backoff\nlet delay = 2000;\nlet doc: any;\nfor (let i = 0; i < 20; i++) {\n  await new Promise((r) => setTimeout(r, delay));\n  doc = await fetch(`${BASE}/documents/${document.id}`, { headers }).then((r) => r.json());\n  if (doc.status === "completed") break;\n  if (doc.status === "error") throw new Error(`Extraction failed: ${doc.error}`);\n  delay = Math.min(delay * 2, 30_000);\n}\n\n// Step 3: Retrieve extracted data\nconst { data: extractions } = await fetch(\n  `${BASE}/documents/${document.id}/extractions`, { headers }\n).then((r) => r.json());\nconsole.log(extractions[0].data);\n// \u2192 { vendor_name: "Acme Corp", total_amount: 1250.00, ... }\n```\n\nRecommended polling: 2s initial, exponential backoff (2\u21924\u21928\u219216\u219230s cap),\ntimeout after 5 minutes.\n\n**Alternative \u2014 Webhooks:** Configure a delivery destination and listen for\n`document.extracted` events. See the Delivery tag.\n\n**Job status state machine:**\n`pending` \u2192 `queued` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Performance\n\n| Document size | Expected latency | Max timeout |\n|---------------|------------------|-------------|\n| 1\u20135 pages     | Sync, <3s        | 30s         |\n| 6\u201350 pages    | <30s average     | 5 min       |\n| 50+ pages     | <5 min average   | 30 min      |\n\n**Uptime SLA:** 99.5% (Build), 99.9% (Scale), custom (Enterprise).\n\n**Max file size:** 500 MB. JSON request bodies (schemas, jobs): 1 MB.\n\n**Idempotency:** Pass `Idempotency-Key` header on POST requests. Keys are\nvalid for 24 hours and scoped per API key. Duplicates return the cached\nresponse with `cached: true`.\n',
     contact: {
       name: "Talonic Support",
       email: "support@talonic.ai",
@@ -2921,13 +2921,18 @@ var openapi_default = {
         ],
         responses: {
           "200": {
-            description: "Array of delivery destinations for the authenticated customer.",
+            description: "Delivery destinations for the authenticated customer.",
             content: {
               "application/json": {
                 schema: {
-                  type: "array",
-                  items: {
-                    $ref: "#/components/schemas/Destination"
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        $ref: "#/components/schemas/Destination"
+                      }
+                    }
                   }
                 }
               }
@@ -3149,13 +3154,18 @@ var openapi_default = {
         ],
         responses: {
           "200": {
-            description: "Array of delivery bindings for the authenticated customer.",
+            description: "Delivery bindings for the authenticated customer.",
             content: {
               "application/json": {
                 schema: {
-                  type: "array",
-                  items: {
-                    $ref: "#/components/schemas/DeliveryBinding"
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        $ref: "#/components/schemas/DeliveryBinding"
+                      }
+                    }
                   }
                 }
               }
@@ -3661,13 +3671,18 @@ var openapi_default = {
         ],
         responses: {
           "200": {
-            description: "Array of dead-letter rows.",
+            description: "Dead-letter queue entries.",
             content: {
               "application/json": {
                 schema: {
-                  type: "array",
-                  items: {
-                    $ref: "#/components/schemas/DeliveryDeadLetter"
+                  type: "object",
+                  properties: {
+                    data: {
+                      type: "array",
+                      items: {
+                        $ref: "#/components/schemas/DeliveryDeadLetter"
+                      }
+                    }
                   }
                 }
               }
@@ -11629,7 +11644,8 @@ var openapi_default = {
                 },
                 data_type: {
                   type: "string",
-                  example: "string"
+                  description: "Field type hint. Accepted values: string, number, integer, boolean, date, array, object. Defaults to string. Extracted values are returned as the specified type when possible.",
+                  example: "number"
                 },
                 description: {
                   type: "string"

package/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Talonic API",
     "version": "1.0.0",
-    "description": "Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (≤5 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` — poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {\"async\": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` → `processing` → `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` — daily cap for the namespace\n- `X-RateLimit-Remaining` — requests left today\n- `X-RateLimit-Reset` — ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1–100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  \"statusCode\": 400,\n  \"code\": \"VALIDATION_ERROR\",\n  \"error\": \"Bad Request\",\n  \"message\": \"name is required.\",\n  \"retryable\": false,\n  \"timestamp\": \"2026-04-25T14:30:00.000Z\",\n  \"path\": \"/v1/schemas\"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Flow\n\nDocuments ≤5 pages return results synchronously (`200`). Larger documents\n— or any request with `options: {\"async\": true}` — return `202 Accepted`.\n\n**1. Submit extraction:**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H \"Authorization: Bearer tlnc_live_abc123\" \\\n  -F \"file=@contract.pdf\" \\\n  -F 'options={\"async\": true}'\n```\n\nResponse `202`:\n```json\n{\n  \"request_id\": \"req_x7y8z9a0\",\n  \"status\": \"processing\",\n  \"document\": { \"id\": \"f0e1d2c3-b4a5-9687-8765-432109876543\" },\n  \"poll_url\": \"/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543\"\n}\n```\n\n**2. Poll until complete:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543 \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\nWhile processing: `{ \"status\": \"processing\" }`\nWhen done: `{ \"status\": \"completed\" }`\n\n**3. Retrieve results:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543/extractions \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\n**Python — complete async flow with exponential backoff:**\n\n```python\nimport time\nimport requests\n\nAPI_KEY = \"tlnc_live_...\"\nBASE = \"https://api.talonic.com/v1\"\nHEADERS = {\"Authorization\": f\"Bearer {API_KEY}\"}\n\n# Step 1: Submit async extraction\nresp = requests.post(f\"{BASE}/extract\",\n    headers=HEADERS,\n    files={\"file\": open(\"contract.pdf\", \"rb\")},\n    data={\"options\": '{\"async\": true}'})\ndoc_id = resp.json()[\"document\"][\"id\"]\n\n# Step 2: Poll with exponential backoff (2s → 4s → 8s → 16s → 30s cap)\ndelay = 2\nfor _ in range(20):\n    time.sleep(delay)\n    doc = requests.get(f\"{BASE}/documents/{doc_id}\", headers=HEADERS).json()\n    if doc[\"status\"] == \"completed\":\n        break\n    if doc[\"status\"] == \"error\":\n        raise Exception(f\"Extraction failed: {doc.get('error')}\")\n    delay = min(delay * 2, 30)\n\n# Step 3: Retrieve extracted data\nextractions = requests.get(\n    f\"{BASE}/documents/{doc_id}/extractions\", headers=HEADERS).json()\ndata = extractions[\"data\"][0][\"data\"]\nconfidence = extractions[\"data\"][0][\"confidence\"][\"overall\"]\nprint(f\"Extracted {len(data)} fields (confidence: {confidence})\")\nprint(data)\n# → {\"vendor_name\": \"Acme Corp\", \"total_amount\": 1250.00, ...}\n```\n\n**TypeScript — same flow:**\n\n```typescript\nconst API_KEY = \"tlnc_live_...\";\nconst BASE = \"https://api.talonic.com/v1\";\nconst headers = { Authorization: `Bearer ${API_KEY}` };\n\n// Step 1: Submit async extraction\nconst form = new FormData();\nform.append(\"file\", fs.createReadStream(\"contract.pdf\"));\nform.append(\"options\", '{\"async\": true}');\nconst { document } = await fetch(`${BASE}/extract`, {\n  method: \"POST\", headers, body: form,\n}).then((r) => r.json());\n\n// Step 2: Poll with exponential backoff\nlet delay = 2000;\nlet doc: any;\nfor (let i = 0; i < 20; i++) {\n  await new Promise((r) => setTimeout(r, delay));\n  doc = await fetch(`${BASE}/documents/${document.id}`, { headers }).then((r) => r.json());\n  if (doc.status === \"completed\") break;\n  if (doc.status === \"error\") throw new Error(`Extraction failed: ${doc.error}`);\n  delay = Math.min(delay * 2, 30_000);\n}\n\n// Step 3: Retrieve extracted data\nconst { data: extractions } = await fetch(\n  `${BASE}/documents/${document.id}/extractions`, { headers }\n).then((r) => r.json());\nconsole.log(extractions[0].data);\n// → { vendor_name: \"Acme Corp\", total_amount: 1250.00, ... }\n```\n\nRecommended polling: 2s initial, exponential backoff (2→4→8→16→30s cap),\ntimeout after 5 minutes.\n\n**Alternative — Webhooks:** Configure a delivery destination and listen for\n`document.extracted` events. See the Delivery tag.\n\n**Job status state machine:**\n`pending` → `queued` → `processing` → `complete` | `failed`\n\n## Performance\n\n| Document size | Expected latency | Max timeout |\n|---------------|------------------|-------------|\n| 1–5 pages     | Sync, <3s        | 30s         |\n| 6–50 pages    | <30s average     | 5 min       |\n| 50+ pages     | <5 min average   | 30 min      |\n\n**Uptime SLA:** 99.5% (Build), 99.9% (Scale), custom (Enterprise).\n\n**Max file size:** 500 MB. JSON request bodies (schemas, jobs): 1 MB.\n\n**Idempotency:** Pass `Idempotency-Key` header on POST requests. Keys are\nvalid for 24 hours and scoped per API key. Duplicates return the cached\nresponse with `cached: true`.\n",
+    "description": "Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Quick Start\n\n**1. Get your API key**\n\nSign up at [app.talonic.com](https://app.talonic.com) → Settings → API Keys → Create key.\nKeys start with `tlnc_live_` (production) or `tlnc_test_` (sandbox).\nAll examples below use `tlnc_live_abc123` as a placeholder.\n\n**2. Extract your first document**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H \"Authorization: Bearer tlnc_live_abc123\" \\\n  -F \"file=@invoice.pdf\" \\\n  -F 'schema={\"properties\":{\"vendor_name\":{\"type\":\"string\"},\"total_amount\":{\"type\":\"number\"},\"invoice_date\":{\"type\":\"string\"}}}'\n```\n\n**Python:**\n```python\nimport requests\nresp = requests.post(\"https://api.talonic.com/v1/extract\",\n    headers={\"Authorization\": \"Bearer tlnc_live_abc123\"},\n    files={\"file\": open(\"invoice.pdf\", \"rb\")},\n    data={\"schema\": '{\"properties\":{\"vendor_name\":{\"type\":\"string\"},\"total_amount\":{\"type\":\"number\"},\"invoice_date\":{\"type\":\"string\"}}}'})\nprint(resp.json()[\"data\"])\n```\n\n**TypeScript:**\n```typescript\nconst form = new FormData();\nform.append(\"file\", fs.createReadStream(\"invoice.pdf\"));\nform.append(\"schema\", '{\"properties\":{\"vendor_name\":{\"type\":\"string\"},\"total_amount\":{\"type\":\"number\"},\"invoice_date\":{\"type\":\"string\"}}}');\nconst res = await fetch(\"https://api.talonic.com/v1/extract\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer tlnc_live_abc123\" },\n  body: form,\n}).then(r => r.json());\nconsole.log(res.data);\n```\n\n**3. What you get back**\n\n```json\n{\n  \"extraction_id\": \"d1a2b3c4-5678-9abc-def0-1234567890ab\",\n  \"request_id\": \"req_x7y8z9a0b1c2d3e4\",\n  \"status\": \"complete\",\n  \"document\": {\n    \"id\": \"f0e1d2c3-b4a5-9687-8765-432109876543\",\n    \"filename\": \"invoice.pdf\",\n    \"pages\": 2,\n    \"size_bytes\": 184320,\n    \"type_detected\": \"Invoice\",\n    \"language_detected\": \"en\"\n  },\n  \"data\": {\n    \"vendor_name\": \"Acme GmbH\",\n    \"total_amount\": 14250.00,\n    \"invoice_date\": \"2025-03-15\"\n  },\n  \"confidence\": {\n    \"overall\": 0.96,\n    \"fields\": {\n      \"vendor_name\": 0.97,\n      \"total_amount\": 0.94,\n      \"invoice_date\": 0.99\n    }\n  },\n  \"processing\": {\n    \"duration_ms\": 1840,\n    \"pages_processed\": 2,\n    \"region\": \"eu-west\"\n  },\n  \"links\": {\n    \"self\": \"/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab\",\n    \"document\": \"/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543\"\n  }\n}\n```\n\n- **`data`** — extracted fields as key-value pairs matching your schema.\n- **`confidence.fields`** — per-field score from 0 to 1. Above 0.9 is high confidence; below 0.7 flags for review.\n- **`extraction_id`** — use this to retrieve, correct, or deliver results later.\n- Full response schema: [ExtractSyncResponse](#/components/schemas/ExtractSyncResponse)\n\n**4. Next steps**\n\n- **50+ pages?** Use async mode — see [Async Extraction Flow](#section/Async-Extraction-Flow) below.\n- **Reusable schemas** — save field definitions with `POST /v1/schemas`, then pass `schema_id` on future extractions.\n- **Receive results via webhook** — configure a delivery destination and listen for `document.extracted` events. See the [Delivery](#tag/Delivery) tag.\n\n---\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (≤5 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` — poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {\"async\": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` → `processing` → `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` — daily cap for the namespace\n- `X-RateLimit-Remaining` — requests left today\n- `X-RateLimit-Reset` — ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1–100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  \"statusCode\": 400,\n  \"code\": \"VALIDATION_ERROR\",\n  \"error\": \"Bad Request\",\n  \"message\": \"name is required.\",\n  \"retryable\": false,\n  \"timestamp\": \"2026-04-25T14:30:00.000Z\",\n  \"path\": \"/v1/schemas\"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Flow\n\nDocuments ≤5 pages return results synchronously (`200`). Larger documents\n— or any request with `options: {\"async\": true}` — return `202 Accepted`.\n\n**1. Submit extraction:**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H \"Authorization: Bearer tlnc_live_abc123\" \\\n  -F \"file=@contract.pdf\" \\\n  -F 'options={\"async\": true}'\n```\n\nResponse `202`:\n```json\n{\n  \"request_id\": \"req_x7y8z9a0\",\n  \"status\": \"processing\",\n  \"document\": { \"id\": \"f0e1d2c3-b4a5-9687-8765-432109876543\" },\n  \"poll_url\": \"/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543\"\n}\n```\n\n**2. Poll until complete:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543 \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\nWhile processing: `{ \"status\": \"processing\" }`\nWhen done: `{ \"status\": \"completed\" }`\n\n**3. Retrieve results:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543/extractions \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\n**Python — complete async flow with exponential backoff:**\n\n```python\nimport time\nimport requests\n\nAPI_KEY = \"tlnc_live_...\"\nBASE = \"https://api.talonic.com/v1\"\nHEADERS = {\"Authorization\": f\"Bearer {API_KEY}\"}\n\n# Step 1: Submit async extraction\nresp = requests.post(f\"{BASE}/extract\",\n    headers=HEADERS,\n    files={\"file\": open(\"contract.pdf\", \"rb\")},\n    data={\"options\": '{\"async\": true}'})\ndoc_id = resp.json()[\"document\"][\"id\"]\n\n# Step 2: Poll with exponential backoff (2s → 4s → 8s → 16s → 30s cap)\ndelay = 2\nfor _ in range(20):\n    time.sleep(delay)\n    doc = requests.get(f\"{BASE}/documents/{doc_id}\", headers=HEADERS).json()\n    if doc[\"status\"] == \"completed\":\n        break\n    if doc[\"status\"] == \"error\":\n        raise Exception(f\"Extraction failed: {doc.get('error')}\")\n    delay = min(delay * 2, 30)\n\n# Step 3: Retrieve extracted data\nextractions = requests.get(\n    f\"{BASE}/documents/{doc_id}/extractions\", headers=HEADERS).json()\ndata = extractions[\"data\"][0][\"data\"]\nconfidence = extractions[\"data\"][0][\"confidence\"][\"overall\"]\nprint(f\"Extracted {len(data)} fields (confidence: {confidence})\")\nprint(data)\n# → {\"vendor_name\": \"Acme Corp\", \"total_amount\": 1250.00, ...}\n```\n\n**TypeScript — same flow:**\n\n```typescript\nconst API_KEY = \"tlnc_live_...\";\nconst BASE = \"https://api.talonic.com/v1\";\nconst headers = { Authorization: `Bearer ${API_KEY}` };\n\n// Step 1: Submit async extraction\nconst form = new FormData();\nform.append(\"file\", fs.createReadStream(\"contract.pdf\"));\nform.append(\"options\", '{\"async\": true}');\nconst { document } = await fetch(`${BASE}/extract`, {\n  method: \"POST\", headers, body: form,\n}).then((r) => r.json());\n\n// Step 2: Poll with exponential backoff\nlet delay = 2000;\nlet doc: any;\nfor (let i = 0; i < 20; i++) {\n  await new Promise((r) => setTimeout(r, delay));\n  doc = await fetch(`${BASE}/documents/${document.id}`, { headers }).then((r) => r.json());\n  if (doc.status === \"completed\") break;\n  if (doc.status === \"error\") throw new Error(`Extraction failed: ${doc.error}`);\n  delay = Math.min(delay * 2, 30_000);\n}\n\n// Step 3: Retrieve extracted data\nconst { data: extractions } = await fetch(\n  `${BASE}/documents/${document.id}/extractions`, { headers }\n).then((r) => r.json());\nconsole.log(extractions[0].data);\n// → { vendor_name: \"Acme Corp\", total_amount: 1250.00, ... }\n```\n\nRecommended polling: 2s initial, exponential backoff (2→4→8→16→30s cap),\ntimeout after 5 minutes.\n\n**Alternative — Webhooks:** Configure a delivery destination and listen for\n`document.extracted` events. See the Delivery tag.\n\n**Job status state machine:**\n`pending` → `queued` → `processing` → `complete` | `failed`\n\n## Performance\n\n| Document size | Expected latency | Max timeout |\n|---------------|------------------|-------------|\n| 1–5 pages     | Sync, <3s        | 30s         |\n| 6–50 pages    | <30s average     | 5 min       |\n| 50+ pages     | <5 min average   | 30 min      |\n\n**Uptime SLA:** 99.5% (Build), 99.9% (Scale), custom (Enterprise).\n\n**Max file size:** 500 MB. JSON request bodies (schemas, jobs): 1 MB.\n\n**Idempotency:** Pass `Idempotency-Key` header on POST requests. Keys are\nvalid for 24 hours and scoped per API key. Duplicates return the cached\nresponse with `cached: true`.\n",
     "contact": {
       "name": "Talonic Support",
       "email": "support@talonic.ai",
@@ -2902,13 +2902,18 @@
         ],
         "responses": {
           "200": {
-            "description": "Array of delivery destinations for the authenticated customer.",
+            "description": "Delivery destinations for the authenticated customer.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Destination"
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Destination"
+                      }
+                    }
                   }
                 }
               }
@@ -3130,13 +3135,18 @@
         ],
         "responses": {
           "200": {
-            "description": "Array of delivery bindings for the authenticated customer.",
+            "description": "Delivery bindings for the authenticated customer.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/DeliveryBinding"
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/DeliveryBinding"
+                      }
+                    }
                   }
                 }
               }
@@ -3642,13 +3652,18 @@
         ],
         "responses": {
           "200": {
-            "description": "Array of dead-letter rows.",
+            "description": "Dead-letter queue entries.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/DeliveryDeadLetter"
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/DeliveryDeadLetter"
+                      }
+                    }
                   }
                 }
               }
@@ -11610,7 +11625,8 @@
                 },
                 "data_type": {
                   "type": "string",
-                  "example": "string"
+                  "description": "Field type hint. Accepted values: string, number, integer, boolean, date, array, object. Defaults to string. Extracted values are returned as the specified type when possible.",
+                  "example": "number"
                 },
                 "description": {
                   "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talonic/docs",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Talonic documentation components — API Reference & Platform Guide",
   "license": "UNLICENSED",
   "private": false,