@talonic/docs 0.20.26 → 0.20.28

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## 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% (Pro), 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% (Pro), 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",
@@ -55,7 +55,7 @@
     },
     {
       "name": "Delivery",
-      "description": "Outbound delivery pipeline \u2014 routing rules, delivery destinations (webhook, SFTP,\nS3, Azure Blob, Google Drive, OneDrive), bindings, filters, and the delivery\nhistory/DLQ/events log.\n\n## Webhook Contract\n\n**Event payload:**\n```json\n{\n  \"event\": {\n    \"event_type\": \"document.extracted\",\n    \"event_id\": \"42\",\n    \"binding_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"idempotency_key\": \"c9f3a7e1b2d4f6a8e0c2d4f6a8e0c2d4\",\n    \"attempt\": 1,\n    \"delivered_at\": \"2026-04-25T14:30:00.000Z\"\n  },\n  \"payload\": { \"document_id\": \"...\", \"data\": { \"...extracted fields...\" } }\n}\n```\n\n**Event types:** `document.extracted`, `document.extraction_failed`,\n`run.dataspace.completed`, `run.dataspace.failed`, `result.dataspace.completed`,\n`result.dataspace.failed`, `run.structuring.completed`, `run.structuring.failed`,\n`run.resolution.completed`, `run.resolution.failed`, `run.extraction.completed`,\n`run.extraction.failed`, `result.flagged`, `result.approved`, `result.rejected`,\n`delivery.item.completed`, `delivery.item.failed`.\n\n**Signature verification (HMAC-SHA256):**\n\nHeader: `X-Talonic-Signature: t=1714060200000,v1=abc123...`\n\n```javascript\nconst crypto = require('crypto');\nconst [tPart, vPart] = signature.split(',');\nconst timestamp = tPart.split('=')[1];\nconst received  = vPart.split('=')[1];\nconst expected  = crypto.createHmac('sha256', signingSecret)\n  .update(timestamp + '.' + rawBody).digest('hex');\nconst valid = crypto.timingSafeEqual(\n  Buffer.from(received), Buffer.from(expected));\n```\n\n**Retry policy:** Up to 7 attempts \u2014 0s, 30s, 2m, 8m, 30m, 2h, 8h (~10.5h total).\nHTTP 429/5xx are retryable. HTTP 4xx (except 408) goes to DLQ immediately.\n\n**Dead-letter queue recovery:** When all retries are exhausted, the delivery\nlands in the DLQ. List failed deliveries with `GET /v1/delivery/dlq`\n(filterable by `binding_id` and `error_code`). Inspect a single entry with\n`GET /v1/delivery/dlq/{id}`. Replay with `POST /v1/delivery/dlq/{id}/replay`\n\u2014 this deletes the DLQ entry, re-signs the payload with the current\nsigning secret, resets the retry counter to attempt 1, and re-enqueues\nthe delivery through the full backoff ladder.\n"
+      "description": "Outbound delivery pipeline — routing rules, delivery destinations (webhook, SFTP,\nS3, Azure Blob, Google Drive, OneDrive), bindings, filters, and the delivery\nhistory/DLQ/events log.\n\n## Webhook Contract\n\n**Event payload:**\n```json\n{\n  \"event\": {\n    \"event_type\": \"document.extracted\",\n    \"event_id\": \"42\",\n    \"binding_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"idempotency_key\": \"c9f3a7e1b2d4f6a8e0c2d4f6a8e0c2d4\",\n    \"attempt\": 1,\n    \"delivered_at\": \"2026-04-25T14:30:00.000Z\"\n  },\n  \"payload\": { \"document_id\": \"...\", \"data\": { \"...extracted fields...\" } }\n}\n```\n\n**Event types:** `document.extracted`, `document.extraction_failed`,\n`run.dataspace.completed`, `run.dataspace.failed`, `result.dataspace.completed`,\n`result.dataspace.failed`, `run.structuring.completed`, `run.structuring.failed`,\n`run.resolution.completed`, `run.resolution.failed`, `run.extraction.completed`,\n`run.extraction.failed`, `result.flagged`, `result.approved`, `result.rejected`,\n`delivery.item.completed`, `delivery.item.failed`.\n\n**Signature verification (HMAC-SHA256):**\n\nHeader: `X-Talonic-Signature: t=1714060200000,v1=abc123...`\n\n```javascript\nconst crypto = require('crypto');\nconst [tPart, vPart] = signature.split(',');\nconst timestamp = tPart.split('=')[1];\nconst received  = vPart.split('=')[1];\nconst expected  = crypto.createHmac('sha256', signingSecret)\n  .update(timestamp + '.' + rawBody).digest('hex');\nconst valid = crypto.timingSafeEqual(\n  Buffer.from(received), Buffer.from(expected));\n```\n\n**Retry policy:** Up to 7 attempts — 0s, 30s, 2m, 8m, 30m, 2h, 8h (~10.5h total).\nHTTP 429/5xx are retryable. HTTP 4xx (except 408) goes to DLQ immediately.\n\n**Dead-letter queue recovery:** When all retries are exhausted, the delivery\nlands in the DLQ. List failed deliveries with `GET /v1/delivery/dlq`\n(filterable by `binding_id` and `error_code`). Inspect a single entry with\n`GET /v1/delivery/dlq/{id}`. Replay with `POST /v1/delivery/dlq/{id}/replay`\n— this deletes the DLQ entry, re-signs the payload with the current\nsigning secret, resets the retry counter to attempt 1, and re-enqueues\nthe delivery through the full backoff ladder.\n"
     },
     {
       "name": "Intelligence",
@@ -139,7 +139,7 @@
                   },
                   "options": {
                     "type": "string",
-                    "description": "JSON string of extraction options.\n- `async` (boolean) \u2014 force async (`true`) or sync (`false`) processing.\n"
+                    "description": "JSON string of extraction options.\n- `async` (boolean) — force async (`true`) or sync (`false`) processing.\n"
                   }
                 }
               },
@@ -1950,7 +1950,7 @@
                       "batch"
                     ],
                     "default": "realtime",
-                    "description": "\"realtime\" (default) \u2014 processed immediately.\n\"batch\" \u2014 50% cost discount, results within 48 hours.\n"
+                    "description": "\"realtime\" (default) — processed immediately.\n\"batch\" — 50% cost discount, results within 48 hours.\n"
                   }
                 }
               }
@@ -2427,7 +2427,7 @@
       "put": {
         "operationId": "updateMatchingConfig",
         "summary": "Update a matching configuration",
-        "description": "Partial update \u2014 only provided keys are applied.",
+        "description": "Partial update — only provided keys are applied.",
         "tags": [
           "Intelligence"
         ],
@@ -3110,7 +3110,7 @@
       "post": {
         "operationId": "testDeliveryDestination",
         "summary": "Live-ping a destination through the full transport envelope",
-        "description": "Exercises the complete delivery envelope (SSRF guard, payload cap, rate\nlimit, retry ladder is disabled \u2014 `max_attempts: 1`) with a tiny test\npayload. The returned `success` field reflects whether the connector's\n`deliver()` call returned a non-retryable success; check `httpStatus`\nand `message` for details.\n",
+        "description": "Exercises the complete delivery envelope (SSRF guard, payload cap, rate\nlimit, retry ladder is disabled — `max_attempts: 1`) with a tiny test\npayload. The returned `success` field reflects whether the connector's\n`deliver()` call returned a non-retryable success; check `httpStatus`\nand `message` for details.\n",
         "tags": [
           "Delivery"
         ],
@@ -3344,7 +3344,7 @@
       "post": {
         "operationId": "previewDeliveryBinding",
         "summary": "Synthetic-signal dry-run preview",
-        "description": "Builds a synthetic {DeliveryEvent} that matches the binding's\n`signal_filter.event_type` (overlaying any `signal_filter.match`\nconstraints), then walks the delivery pipeline up to \u2014 but NOT\nincluding \u2014 `connector.deliver()`:\n`resolver.resolve(signal) \u2192 projectFieldMap \u2192 serializer.serialize`.\n\nWhen the resolver can load a real entity, `sample_mode` is `\"real\"`\nand `projected` / `serialized` / `wire_preview` are populated. If the\nresolver throws (typically `EntityMissingError` because the synthetic\nentity id doesn't exist in this tenant), the service falls back to\n`sample_mode: \"structural\"` \u2014 it returns the resolver's declared\n`shape` without concrete data. The preview never makes a network\ncall, never inserts a delivery row, and never touches the DLQ.\n",
+        "description": "Builds a synthetic {DeliveryEvent} that matches the binding's\n`signal_filter.event_type` (overlaying any `signal_filter.match`\nconstraints), then walks the delivery pipeline up to — but NOT\nincluding — `connector.deliver()`:\n`resolver.resolve(signal) → projectFieldMap → serializer.serialize`.\n\nWhen the resolver can load a real entity, `sample_mode` is `\"real\"`\nand `projected` / `serialized` / `wire_preview` are populated. If the\nresolver throws (typically `EntityMissingError` because the synthetic\nentity id doesn't exist in this tenant), the service falls back to\n`sample_mode: \"structural\"` — it returns the resolver's declared\n`shape` without concrete data. The preview never makes a network\ncall, never inserts a delivery row, and never touches the DLQ.\n",
         "tags": [
           "Delivery"
         ],
@@ -3355,7 +3355,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Preview response \u2014 real dry-run or structural fallback.",
+            "description": "Preview response — real dry-run or structural fallback.",
             "content": {
               "application/json": {
                 "schema": {
@@ -3363,7 +3363,7 @@
                 },
                 "examples": {
                   "real": {
-                    "summary": "Real dry-run \u2014 resolver loaded a synthetic entity and every pipeline stage ran.",
+                    "summary": "Real dry-run — resolver loaded a synthetic entity and every pipeline stage ran.",
                     "value": {
                       "available": true,
                       "sample_mode": "real",
@@ -3399,7 +3399,7 @@
                     }
                   },
                   "structural": {
-                    "summary": "Structural fallback \u2014 the resolver couldn't load the synthetic entity, so only the declared shape is returned.",
+                    "summary": "Structural fallback — the resolver couldn't load the synthetic entity, so only the declared shape is returned.",
                     "value": {
                       "available": true,
                       "sample_mode": "structural",
@@ -3602,7 +3602,7 @@
       "post": {
         "operationId": "replayDeliveryItem",
         "summary": "Re-enqueue a delivery attempt",
-        "description": "Enqueues a new attempt for the binding/event pair. Generates a new\nidempotency key \u2014 replays are new attempts, never mutations.\n",
+        "description": "Enqueues a new attempt for the binding/event pair. Generates a new\nidempotency key — replays are new attempts, never mutations.\n",
         "tags": [
           "Delivery"
         ],
@@ -3771,7 +3771,7 @@
       "post": {
         "operationId": "replayDeliveryDlq",
         "summary": "Re-enqueue a dead-letter row",
-        "description": "Inserts a fresh BullMQ job for the binding/event pair. The DLQ row is\nleft in place (append-only history) \u2014 it stays readable until\nexplicitly dismissed.\n",
+        "description": "Inserts a fresh BullMQ job for the binding/event pair. The DLQ row is\nleft in place (append-only history) — it stays readable until\nexplicitly dismissed.\n",
         "tags": [
           "Delivery"
         ],
@@ -3812,7 +3812,7 @@
       "get": {
         "operationId": "listDeliveryEvents",
         "summary": "List outbox events",
-        "description": "Raw outbox rows with their processing status. Filter by `event_type` \u2014\npagination via `limit` / `offset`.\n",
+        "description": "Raw outbox rows with their processing status. Filter by `event_type` —\npagination via `limit` / `offset`.\n",
         "tags": [
           "Delivery"
         ],
@@ -3878,7 +3878,7 @@
       "post": {
         "operationId": "replayDeliveryEvent",
         "summary": "Re-poll an outbox event",
-        "description": "Clears `processed_at` and `processing_status` so the poller re-picks\nthe row on the next tick. The event ID is BIGSERIAL (string) \u2014 no\nUUID validation.\n",
+        "description": "Clears `processed_at` and `processing_status` so the poller re-picks\nthe row on the next tick. The event ID is BIGSERIAL (string) — no\nUUID validation.\n",
         "tags": [
           "Delivery"
         ],
@@ -4964,7 +4964,7 @@
       "get": {
         "operationId": "getCase",
         "summary": "Get a case by key",
-        "description": "Case keys are 8\u201364 char hex strings (SHA-256 hash of the canonical\nentity-value set that defines the cluster). Returns the label,\nnarrative, linked documents, and anomaly count.\n",
+        "description": "Case keys are 8–64 char hex strings (SHA-256 hash of the canonical\nentity-value set that defines the cluster). Returns the label,\nnarrative, linked documents, and anomaly count.\n",
         "tags": [
           "Intelligence"
         ],
@@ -5063,7 +5063,7 @@
                       "items": {
                         "type": "object",
                         "additionalProperties": true,
-                        "description": "Category \u2192 subcategory \u2192 types hierarchy. Shape is defined by `config/document-ontology.yaml`."
+                        "description": "Category → subcategory → types hierarchy. Shape is defined by `config/document-ontology.yaml`."
                       }
                     }
                   }
@@ -5466,7 +5466,7 @@
                       "items": {
                         "type": "object",
                         "additionalProperties": true,
-                        "description": "Row object \u2014 keys match the dataset's column schema."
+                        "description": "Row object — keys match the dataset's column schema."
                       }
                     },
                     "pagination": {
@@ -7757,7 +7757,7 @@
       "get": {
         "operationId": "getTelemetrySchemaSummary",
         "summary": "Get telemetry summary for a schema",
-        "description": "Aggregate structuring metrics for a schema \u2014 capture hit rate, synthesize rate, strategy distribution, tier funnel.",
+        "description": "Aggregate structuring metrics for a schema — capture hit rate, synthesize rate, strategy distribution, tier funnel.",
         "tags": [
           "Platform"
         ],
@@ -7839,7 +7839,7 @@
       "get": {
         "operationId": "getTelemetrySchemaFields",
         "summary": "Get per-field telemetry for a schema",
-        "description": "Field-level structuring metrics \u2014 per-field state distribution, capture rates, and strategy breakdown.",
+        "description": "Field-level structuring metrics — per-field state distribution, capture rates, and strategy breakdown.",
         "tags": [
           "Platform"
         ],
@@ -10362,7 +10362,7 @@
       "get": {
         "operationId": "getAgentContext",
         "summary": "Get workspace context",
-        "description": "Returns a snapshot of the workspace's current state for the embedded\nAI agent \u2014 document counts, active schemas, recent jobs, and feature\nflags. Useful for bootstrapping agent conversations.\n",
+        "description": "Returns a snapshot of the workspace's current state for the embedded\nAI agent — document counts, active schemas, recent jobs, and feature\nflags. Useful for bootstrapping agent conversations.\n",
         "tags": [
           "Platform"
         ],
@@ -14814,6 +14814,127 @@
           }
         }
       }
+    },
+    "/v1/usage/credits": {
+      "get": {
+        "operationId": "getCreditUsageByFunction",
+        "summary": "Per-function credit consumption",
+        "description": "Credit consumption grouped by platform function (operation_type) from the customer-pay ledger, plus the window total. Shows where credits went (extraction vs structuring vs intelligence ops). Populates once metering is enforcing.",
+        "tags": [
+          "Usage"
+        ],
+        "parameters": [
+          {
+            "name": "days",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 365,
+              "default": 30
+            },
+            "description": "Trailing reporting window in days (default 30)."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Per-function credit consumption.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "period_days": {
+                      "type": "integer"
+                    },
+                    "total_credits": {
+                      "type": "integer"
+                    },
+                    "by_function": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "operation_type": {
+                            "type": "string"
+                          },
+                          "operations": {
+                            "type": "integer"
+                          },
+                          "credits": {
+                            "type": "integer"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/pricing": {
+      "get": {
+        "operationId": "getPricing",
+        "summary": "Credit pricing catalog",
+        "description": "Public (unauthenticated) machine-readable credit pricing catalog: fixed per-unit credit rates, EUR equivalents, the credits-per-EUR conversion rate, and processing-mode multipliers (e.g. batch at 0.5x). Predict spend before running anything.",
+        "tags": [
+          "Pricing"
+        ],
+        "responses": {
+          "200": {
+            "description": "The credit pricing catalog.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "currency": {
+                      "type": "string",
+                      "example": "EUR"
+                    },
+                    "credits_per_eur": {
+                      "type": "number"
+                    },
+                    "multipliers": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "number"
+                      }
+                    },
+                    "units": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "unit": {
+                            "type": "string"
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "credits": {
+                            "type": "number"
+                          },
+                          "eur": {
+                            "type": "number"
+                          },
+                          "free": {
+                            "type": "boolean"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -14846,7 +14967,7 @@
           "maximum": 100,
           "default": 20
         },
-        "description": "Maximum number of items to return (1\u2013100)."
+        "description": "Maximum number of items to return (1–100)."
       },
       "Cursor": {
         "name": "cursor",
@@ -15178,7 +15299,7 @@
               },
               "attempt": {
                 "type": "integer",
-                "description": "Delivery attempt number (1\u20137).",
+                "description": "Delivery attempt number (1–7).",
                 "example": 1
               },
               "delivered_at": {
@@ -16103,7 +16224,7 @@
               "integer",
               "null"
             ],
-            "description": "Percentage complete (0\u2013100). Only present while `processing`.",
+            "description": "Percentage complete (0–100). Only present while `processing`.",
             "example": 45
           },
           "estimated_seconds_remaining": {
@@ -16707,7 +16828,7 @@
           },
           "boolean_format": {
             "type": "array",
-            "description": "Exactly 2 strings \u2014 `[true_value, false_value]`.",
+            "description": "Exactly 2 strings — `[true_value, false_value]`.",
             "minItems": 2,
             "maxItems": 2,
             "items": {
@@ -16753,7 +16874,7 @@
           },
           "boolean_format": {
             "type": "array",
-            "description": "Exactly 2 strings \u2014 `[true_value, false_value]`.",
+            "description": "Exactly 2 strings — `[true_value, false_value]`.",
             "minItems": 2,
             "maxItems": 2,
             "items": {
@@ -16768,7 +16889,7 @@
       },
       "DialectUpdateRequest": {
         "type": "object",
-        "description": "Partial update \u2014 only supplied keys are patched.",
+        "description": "Partial update — only supplied keys are patched.",
         "properties": {
           "name": {
             "type": "string"
@@ -16800,7 +16921,7 @@
       },
       "MatchingFieldMapping": {
         "type": "object",
-        "description": "Field-mapping entry linking an extracted field to a reference-data column.\nThe shape below is illustrative \u2014 the platform accepts any object shape and\napplies matching using the documented keys when present.\n",
+        "description": "Field-mapping entry linking an extracted field to a reference-data column.\nThe shape below is illustrative — the platform accepts any object shape and\napplies matching using the documented keys when present.\n",
         "additionalProperties": true,
         "properties": {
           "extracted_field": {
@@ -16962,7 +17083,7 @@
       },
       "MatchingConfigUpdateRequest": {
         "type": "object",
-        "description": "Partial update \u2014 only provided keys are applied.",
+        "description": "Partial update — only provided keys are applied.",
         "properties": {
           "name": {
             "type": "string"
@@ -17269,7 +17390,7 @@
       },
       "RoutingRuleUpdateRequest": {
         "type": "object",
-        "description": "Partial update \u2014 only supplied keys are patched.",
+        "description": "Partial update — only supplied keys are patched.",
         "properties": {
           "name": {
             "type": "string"
@@ -17323,7 +17444,7 @@
           },
           "type": {
             "type": "string",
-            "description": "Connector type discriminant \u2014 resolves to a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.",
+            "description": "Connector type discriminant — resolves to a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.",
             "example": "webhook"
           },
           "config": {
@@ -17419,7 +17540,7 @@
       },
       "UpdateDestinationRequest": {
         "type": "object",
-        "description": "Partial update \u2014 every field optional. Only supplied fields are written.",
+        "description": "Partial update — every field optional. Only supplied fields are written.",
         "properties": {
           "name": {
             "type": "string"
@@ -17517,7 +17638,7 @@
       },
       "FieldMap": {
         "type": "object",
-        "description": "Declarative projection applied between resolver output and serializer\ninput. Operations run in fixed order: drop \u2192 rename \u2192 static.\n",
+        "description": "Declarative projection applied between resolver output and serializer\ninput. Operations run in fixed order: drop → rename → static.\n",
         "properties": {
           "rules": {
             "type": "array",
@@ -17540,7 +17661,7 @@
           "static": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Literal key/value pairs added last \u2014 always wins collisions."
+            "description": "Literal key/value pairs added last — always wins collisions."
           },
           "drop": {
             "type": "array",
@@ -17700,7 +17821,7 @@
       },
       "UpdateBindingRequest": {
         "type": "object",
-        "description": "Partial update \u2014 every field optional.",
+        "description": "Partial update — every field optional.",
         "properties": {
           "name": {
             "type": "string"
@@ -17874,7 +17995,7 @@
             ],
             "format": "uuid",
             "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-            "description": "FK to the last DeliveryItem attempt (nullable \u2014 `ON DELETE SET NULL`)."
+            "description": "FK to the last DeliveryItem attempt (nullable — `ON DELETE SET NULL`)."
           },
           "error_code": {
             "type": "string",
@@ -17906,7 +18027,7 @@
           "created_at",
           "processing_attempts"
         ],
-        "description": "Outbox record (not the typed producer DTO). Represents a single row in\nthe `delivery_events` table. `event_type` is a string discriminant \u2014\nsee `/v1/delivery/catalog/signals` for the exhaustive list.\n",
+        "description": "Outbox record (not the typed producer DTO). Represents a single row in\nthe `delivery_events` table. `event_type` is a string discriminant —\nsee `/v1/delivery/catalog/signals` for the exhaustive list.\n",
         "properties": {
           "id": {
             "type": "string",
@@ -17923,7 +18044,7 @@
           "payload": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Entity IDs only \u2014 deliverable resolvers load content at delivery time."
+            "description": "Entity IDs only — deliverable resolvers load content at delivery time."
           },
           "dedup_key": {
             "type": [
@@ -17991,7 +18112,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Empty for slice-2 stub resolvers \u2014 they appear in the list but never route."
+            "description": "Empty for slice-2 stub resolvers — they appear in the list but never route."
           },
           "shape": {
             "oneOf": [
@@ -18132,7 +18253,7 @@
           },
           "supports_kinds": {
             "type": "array",
-            "description": "Deliverable shape kinds this serializer accepts. Probed against a\nminimal synthetic shape per kind \u2014 always reflects the current\nimplementation.\n",
+            "description": "Deliverable shape kinds this serializer accepts. Probed against a\nminimal synthetic shape per kind — always reflects the current\nimplementation.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -18214,7 +18335,7 @@
           "serialized",
           "wire_preview"
         ],
-        "description": "Output of `POST /v1/delivery/bindings/{id}/preview`. When the resolver\nsuccessfully loads a synthetic entity the full pipeline (`resolve \u2192\nprojectFieldMap \u2192 serialize`) runs and `sample_mode=\"real\"`. When the\nresolver throws (commonly `EntityMissingError` on a synthetic id) the\nservice falls back to `sample_mode=\"structural\"` and returns only the\nresolver's declared shape \u2014 `projected`, `serialized`, and\n`wire_preview` are `null` in that case.\n",
+        "description": "Output of `POST /v1/delivery/bindings/{id}/preview`. When the resolver\nsuccessfully loads a synthetic entity the full pipeline (`resolve →\nprojectFieldMap → serialize`) runs and `sample_mode=\"real\"`. When the\nresolver throws (commonly `EntityMissingError` on a synthetic id) the\nservice falls back to `sample_mode=\"structural\"` and returns only the\nresolver's declared shape — `projected`, `serialized`, and\n`wire_preview` are `null` in that case.\n",
         "properties": {
           "available": {
             "type": "boolean",
@@ -18229,7 +18350,7 @@
               "real",
               "structural"
             ],
-            "description": "`real` \u2014 the resolver loaded a synthetic entity and every pipeline\nstage ran. `structural` \u2014 the resolver threw (typically\n`entity_missing`) so only the declared shape is returned.\n"
+            "description": "`real` — the resolver loaded a synthetic entity and every pipeline\nstage ran. `structural` — the resolver threw (typically\n`entity_missing`) so only the declared shape is returned.\n"
           },
           "signal": {
             "type": "object",
@@ -18389,7 +18510,7 @@
                 "additionalProperties": {
                   "type": "string"
                 },
-                "description": "The `X-Talonic-*` headers that would ship on the wire. The\n`X-Talonic-Signature` header, when present, is rendered as\n`t=<preview>,v1=<preview>` \u2014 the preview never computes a real\nHMAC so the signing secret is not exercised.\n"
+                "description": "The `X-Talonic-*` headers that would ship on the wire. The\n`X-Talonic-Signature` header, when present, is rendered as\n`t=<preview>,v1=<preview>` — the preview never computes a real\nHMAC so the signing secret is not exercised.\n"
               }
             }
           },
@@ -18500,7 +18621,7 @@
         }
       },
       "DestinationAuthConfig": {
-        "description": "Destination credential payload. Write-only \u2014 server responses expose\nonly `has_auth_config: boolean`, never the credential values\nthemselves. The `type` field discriminates the concrete shape; valid\nvalues depend on the parent destination's connector `type` (see\n`/v1/delivery/catalog/connectors` for each connector's `auth_types`).\n",
+        "description": "Destination credential payload. Write-only — server responses expose\nonly `has_auth_config: boolean`, never the credential values\nthemselves. The `type` field discriminates the concrete shape; valid\nvalues depend on the parent destination's connector `type` (see\n`/v1/delivery/catalog/connectors` for each connector's `auth_types`).\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/AuthConfigPassword"
@@ -18748,7 +18869,7 @@
           },
           "operator": {
             "type": "string",
-            "description": "Operator identifier (free-form \u2014 e.g. `eq`, `contains`, `between`).",
+            "description": "Operator identifier (free-form — e.g. `eq`, `contains`, `between`).",
             "example": "between"
           },
           "value": {
@@ -21192,4 +21313,4 @@
       }
     }
   }
-}
+}

package/package.json

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