@talonic/docs 0.19.3 → 0.20.1

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) → 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",
+    "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",
     "contact": {
       "name": "Talonic Support",
       "email": "support@talonic.ai",
@@ -55,7 +55,7 @@
     },
     {
       "name": "Delivery",
-      "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"
+      "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"
     },
     {
       "name": "Intelligence",
@@ -123,7 +123,7 @@
                   },
                   "options": {
                     "type": "string",
-                    "description": "JSON string of extraction options.\n- `async` (boolean) — force async (`true`) or sync (`false`) processing.\n"
+                    "description": "JSON string of extraction options.\n- `async` (boolean) \u2014 force async (`true`) or sync (`false`) processing.\n"
                   }
                 }
               },
@@ -1934,7 +1934,7 @@
                       "batch"
                     ],
                     "default": "realtime",
-                    "description": "\"realtime\" (default) — processed immediately.\n\"batch\" — 50% cost discount, results within 48 hours.\n"
+                    "description": "\"realtime\" (default) \u2014 processed immediately.\n\"batch\" \u2014 50% cost discount, results within 48 hours.\n"
                   }
                 }
               }
@@ -2411,7 +2411,7 @@
       "put": {
         "operationId": "updateMatchingConfig",
         "summary": "Update a matching configuration",
-        "description": "Partial update — only provided keys are applied.",
+        "description": "Partial update \u2014 only provided keys are applied.",
         "tags": [
           "Intelligence"
         ],
@@ -3094,7 +3094,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 — `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 \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",
         "tags": [
           "Delivery"
         ],
@@ -3328,7 +3328,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 — 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",
+        "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",
         "tags": [
           "Delivery"
         ],
@@ -3339,7 +3339,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Preview response — real dry-run or structural fallback.",
+            "description": "Preview response \u2014 real dry-run or structural fallback.",
             "content": {
               "application/json": {
                 "schema": {
@@ -3347,7 +3347,7 @@
                 },
                 "examples": {
                   "real": {
-                    "summary": "Real dry-run — resolver loaded a synthetic entity and every pipeline stage ran.",
+                    "summary": "Real dry-run \u2014 resolver loaded a synthetic entity and every pipeline stage ran.",
                     "value": {
                       "available": true,
                       "sample_mode": "real",
@@ -3383,7 +3383,7 @@
                     }
                   },
                   "structural": {
-                    "summary": "Structural fallback — the resolver couldn't load the synthetic entity, so only the declared shape is returned.",
+                    "summary": "Structural fallback \u2014 the resolver couldn't load the synthetic entity, so only the declared shape is returned.",
                     "value": {
                       "available": true,
                       "sample_mode": "structural",
@@ -3586,7 +3586,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 — replays are new attempts, never mutations.\n",
+        "description": "Enqueues a new attempt for the binding/event pair. Generates a new\nidempotency key \u2014 replays are new attempts, never mutations.\n",
         "tags": [
           "Delivery"
         ],
@@ -3755,7 +3755,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) — 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) \u2014 it stays readable until\nexplicitly dismissed.\n",
         "tags": [
           "Delivery"
         ],
@@ -3796,7 +3796,7 @@
       "get": {
         "operationId": "listDeliveryEvents",
         "summary": "List outbox events",
-        "description": "Raw outbox rows with their processing status. Filter by `event_type` —\npagination via `limit` / `offset`.\n",
+        "description": "Raw outbox rows with their processing status. Filter by `event_type` \u2014\npagination via `limit` / `offset`.\n",
         "tags": [
           "Delivery"
         ],
@@ -3862,7 +3862,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) — 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) \u2014 no\nUUID validation.\n",
         "tags": [
           "Delivery"
         ],
@@ -4948,7 +4948,7 @@
       "get": {
         "operationId": "getCase",
         "summary": "Get a case by key",
-        "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",
+        "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",
         "tags": [
           "Intelligence"
         ],
@@ -5047,7 +5047,7 @@
                       "items": {
                         "type": "object",
                         "additionalProperties": true,
-                        "description": "Category → subcategory → types hierarchy. Shape is defined by `config/document-ontology.yaml`."
+                        "description": "Category \u2192 subcategory \u2192 types hierarchy. Shape is defined by `config/document-ontology.yaml`."
                       }
                     }
                   }
@@ -5450,7 +5450,7 @@
                       "items": {
                         "type": "object",
                         "additionalProperties": true,
-                        "description": "Row object — keys match the dataset's column schema."
+                        "description": "Row object \u2014 keys match the dataset's column schema."
                       }
                     },
                     "pagination": {
@@ -7741,7 +7741,7 @@
       "get": {
         "operationId": "getTelemetrySchemaSummary",
         "summary": "Get telemetry summary for a schema",
-        "description": "Aggregate structuring metrics for a schema — capture hit rate, synthesize rate, strategy distribution, tier funnel.",
+        "description": "Aggregate structuring metrics for a schema \u2014 capture hit rate, synthesize rate, strategy distribution, tier funnel.",
         "tags": [
           "Platform"
         ],
@@ -7823,7 +7823,7 @@
       "get": {
         "operationId": "getTelemetrySchemaFields",
         "summary": "Get per-field telemetry for a schema",
-        "description": "Field-level structuring metrics — per-field state distribution, capture rates, and strategy breakdown.",
+        "description": "Field-level structuring metrics \u2014 per-field state distribution, capture rates, and strategy breakdown.",
         "tags": [
           "Platform"
         ],
@@ -10346,7 +10346,7 @@
       "get": {
         "operationId": "getAgentContext",
         "summary": "Get workspace context",
-        "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",
+        "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",
         "tags": [
           "Platform"
         ],
@@ -10458,6 +10458,481 @@
           }
         }
       }
+    },
+    "/v1/registry/query": {
+      "post": {
+        "operationId": "registryQuery",
+        "summary": "Query extracted field values across documents",
+        "description": "Search previously-extracted field values across all documents without re-extraction. Zero AI calls. Filter by field values and select which fields to return. Max 500 rows.",
+        "tags": [
+          "Platform"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "where"
+                ],
+                "properties": {
+                  "where": {
+                    "type": "object",
+                    "description": "Field-value conditions. Keys are field names, values are expected values. All conditions are ANDed.",
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  },
+                  "select": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Field names to return in results. If omitted, returns all fields referenced in where."
+                  },
+                  "limit": {
+                    "type": "integer",
+                    "default": 100,
+                    "maximum": 500,
+                    "description": "Maximum rows to return (default 100, max 500)."
+                  }
+                }
+              },
+              "example": {
+                "where": {
+                  "vendor_name": "Meridian Energy AG",
+                  "contract_year": "2026"
+                },
+                "select": [
+                  "contract_value",
+                  "auto_renew",
+                  "notice_period_days"
+                ],
+                "limit": 50
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Matching documents with their field values.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "document_id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "filename": {
+                            "type": "string"
+                          },
+                          "document_type": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "total": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Missing where or unknown field name."
+          },
+          "401": {
+            "description": "Missing or invalid API key."
+          },
+          "429": {
+            "description": "Rate limit exceeded."
+          }
+        }
+      }
+    },
+    "/v1/saved-filters": {
+      "get": {
+        "operationId": "listSavedFilters",
+        "summary": "List saved filters",
+        "description": "Returns all saved filter configurations, optionally scoped to a source.",
+        "tags": [
+          "Documents"
+        ],
+        "parameters": [
+          {
+            "name": "sourceId",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by source connection."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of saved filters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "conditions": {
+                            "type": "array",
+                            "items": {
+                              "type": "object"
+                            }
+                          },
+                          "search": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "sort": {
+                            "type": "object",
+                            "nullable": true
+                          },
+                          "source_connection_id": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createSavedFilter",
+        "summary": "Create a saved filter",
+        "description": "Persist a filter configuration for reuse.",
+        "tags": [
+          "Documents"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "conditions"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Display name for the saved filter."
+                  },
+                  "conditions": {
+                    "type": "array",
+                    "items": {
+                      "type": "object"
+                    },
+                    "description": "Array of filter conditions."
+                  },
+                  "search": {
+                    "type": "string",
+                    "description": "Optional free-text search."
+                  },
+                  "sort": {
+                    "type": "object",
+                    "description": "Optional sort configuration."
+                  },
+                  "source_connection_id": {
+                    "type": "string",
+                    "description": "Scope to a specific source."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Saved filter created."
+          },
+          "401": {
+            "description": "Missing or invalid API key."
+          }
+        }
+      }
+    },
+    "/v1/saved-filters/{id}": {
+      "delete": {
+        "operationId": "deleteSavedFilter",
+        "summary": "Delete a saved filter",
+        "tags": [
+          "Documents"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Filter deleted."
+          },
+          "404": {
+            "description": "Saved filter not found."
+          }
+        }
+      }
+    },
+    "/v1/webhooks": {
+      "get": {
+        "operationId": "listWebhooks",
+        "summary": "List webhook configurations",
+        "description": "Returns all webhook configurations for the customer.",
+        "tags": [
+          "Delivery"
+        ],
+        "responses": {
+          "200": {
+            "description": "List of webhook configurations.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "url": {
+                            "type": "string",
+                            "format": "uri"
+                          },
+                          "events": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "source_id": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "active": {
+                            "type": "boolean"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createWebhook",
+        "summary": "Create a webhook configuration",
+        "description": "Configure a new webhook endpoint to receive event notifications.",
+        "tags": [
+          "Delivery"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "url",
+                  "events"
+                ],
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "HTTPS endpoint URL."
+                  },
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Event types to subscribe to."
+                  },
+                  "source_id": {
+                    "type": "string",
+                    "description": "Scope to a specific source (optional)."
+                  },
+                  "secret": {
+                    "type": "string",
+                    "description": "Signing secret. Auto-generated if omitted."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Webhook created. Returns the webhook config including the signing secret."
+          },
+          "400": {
+            "description": "Invalid URL or event types."
+          },
+          "401": {
+            "description": "Missing or invalid API key."
+          }
+        }
+      }
+    },
+    "/v1/webhooks/{id}": {
+      "get": {
+        "operationId": "getWebhook",
+        "summary": "Get webhook configuration",
+        "tags": [
+          "Delivery"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook configuration."
+          },
+          "404": {
+            "description": "Webhook not found."
+          }
+        }
+      },
+      "patch": {
+        "operationId": "updateWebhook",
+        "summary": "Update webhook configuration",
+        "tags": [
+          "Delivery"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "format": "uri"
+                  },
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "active": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook updated."
+          },
+          "404": {
+            "description": "Webhook not found."
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteWebhook",
+        "summary": "Delete webhook configuration",
+        "tags": [
+          "Delivery"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook deleted."
+          },
+          "404": {
+            "description": "Webhook not found."
+          }
+        }
+      }
     }
   },
   "components": {
@@ -10490,7 +10965,7 @@
           "maximum": 100,
           "default": 20
         },
-        "description": "Maximum number of items to return (1–100)."
+        "description": "Maximum number of items to return (1\u2013100)."
       },
       "Cursor": {
         "name": "cursor",
@@ -10822,7 +11297,7 @@
               },
               "attempt": {
                 "type": "integer",
-                "description": "Delivery attempt number (1–7).",
+                "description": "Delivery attempt number (1\u20137).",
                 "example": 1
               },
               "delivered_at": {
@@ -11747,7 +12222,7 @@
               "integer",
               "null"
             ],
-            "description": "Percentage complete (0–100). Only present while `processing`.",
+            "description": "Percentage complete (0\u2013100). Only present while `processing`.",
             "example": 45
           },
           "estimated_seconds_remaining": {
@@ -12351,7 +12826,7 @@
           },
           "boolean_format": {
             "type": "array",
-            "description": "Exactly 2 strings — `[true_value, false_value]`.",
+            "description": "Exactly 2 strings \u2014 `[true_value, false_value]`.",
             "minItems": 2,
             "maxItems": 2,
             "items": {
@@ -12397,7 +12872,7 @@
           },
           "boolean_format": {
             "type": "array",
-            "description": "Exactly 2 strings — `[true_value, false_value]`.",
+            "description": "Exactly 2 strings \u2014 `[true_value, false_value]`.",
             "minItems": 2,
             "maxItems": 2,
             "items": {
@@ -12412,7 +12887,7 @@
       },
       "DialectUpdateRequest": {
         "type": "object",
-        "description": "Partial update — only supplied keys are patched.",
+        "description": "Partial update \u2014 only supplied keys are patched.",
         "properties": {
           "name": {
             "type": "string"
@@ -12444,7 +12919,7 @@
       },
       "MatchingFieldMapping": {
         "type": "object",
-        "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",
+        "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",
         "additionalProperties": true,
         "properties": {
           "extracted_field": {
@@ -12606,7 +13081,7 @@
       },
       "MatchingConfigUpdateRequest": {
         "type": "object",
-        "description": "Partial update — only provided keys are applied.",
+        "description": "Partial update \u2014 only provided keys are applied.",
         "properties": {
           "name": {
             "type": "string"
@@ -12913,7 +13388,7 @@
       },
       "RoutingRuleUpdateRequest": {
         "type": "object",
-        "description": "Partial update — only supplied keys are patched.",
+        "description": "Partial update \u2014 only supplied keys are patched.",
         "properties": {
           "name": {
             "type": "string"
@@ -12967,7 +13442,7 @@
           },
           "type": {
             "type": "string",
-            "description": "Connector type discriminant — resolves to a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.",
+            "description": "Connector type discriminant \u2014 resolves to a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.",
             "example": "webhook"
           },
           "config": {
@@ -13063,7 +13538,7 @@
       },
       "UpdateDestinationRequest": {
         "type": "object",
-        "description": "Partial update — every field optional. Only supplied fields are written.",
+        "description": "Partial update \u2014 every field optional. Only supplied fields are written.",
         "properties": {
           "name": {
             "type": "string"
@@ -13161,7 +13636,7 @@
       },
       "FieldMap": {
         "type": "object",
-        "description": "Declarative projection applied between resolver output and serializer\ninput. Operations run in fixed order: drop → rename → static.\n",
+        "description": "Declarative projection applied between resolver output and serializer\ninput. Operations run in fixed order: drop \u2192 rename \u2192 static.\n",
         "properties": {
           "rules": {
             "type": "array",
@@ -13184,7 +13659,7 @@
           "static": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Literal key/value pairs added last — always wins collisions."
+            "description": "Literal key/value pairs added last \u2014 always wins collisions."
           },
           "drop": {
             "type": "array",
@@ -13344,7 +13819,7 @@
       },
       "UpdateBindingRequest": {
         "type": "object",
-        "description": "Partial update — every field optional.",
+        "description": "Partial update \u2014 every field optional.",
         "properties": {
           "name": {
             "type": "string"
@@ -13518,7 +13993,7 @@
             ],
             "format": "uuid",
             "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-            "description": "FK to the last DeliveryItem attempt (nullable — `ON DELETE SET NULL`)."
+            "description": "FK to the last DeliveryItem attempt (nullable \u2014 `ON DELETE SET NULL`)."
           },
           "error_code": {
             "type": "string",
@@ -13550,7 +14025,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 —\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 \u2014\nsee `/v1/delivery/catalog/signals` for the exhaustive list.\n",
         "properties": {
           "id": {
             "type": "string",
@@ -13567,7 +14042,7 @@
           "payload": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Entity IDs only — deliverable resolvers load content at delivery time."
+            "description": "Entity IDs only \u2014 deliverable resolvers load content at delivery time."
           },
           "dedup_key": {
             "type": [
@@ -13635,7 +14110,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Empty for slice-2 stub resolvers — they appear in the list but never route."
+            "description": "Empty for slice-2 stub resolvers \u2014 they appear in the list but never route."
           },
           "shape": {
             "oneOf": [
@@ -13776,7 +14251,7 @@
           },
           "supports_kinds": {
             "type": "array",
-            "description": "Deliverable shape kinds this serializer accepts. Probed against a\nminimal synthetic shape per kind — always reflects the current\nimplementation.\n",
+            "description": "Deliverable shape kinds this serializer accepts. Probed against a\nminimal synthetic shape per kind \u2014 always reflects the current\nimplementation.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -13858,7 +14333,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 →\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",
+        "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",
         "properties": {
           "available": {
             "type": "boolean",
@@ -13873,7 +14348,7 @@
               "real",
               "structural"
             ],
-            "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"
+            "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"
           },
           "signal": {
             "type": "object",
@@ -14033,7 +14508,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>` — 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>` \u2014 the preview never computes a real\nHMAC so the signing secret is not exercised.\n"
               }
             }
           },
@@ -14144,7 +14619,7 @@
         }
       },
       "DestinationAuthConfig": {
-        "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",
+        "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",
         "oneOf": [
           {
             "$ref": "#/components/schemas/AuthConfigPassword"
@@ -14392,7 +14867,7 @@
           },
           "operator": {
             "type": "string",
-            "description": "Operator identifier (free-form — e.g. `eq`, `contains`, `between`).",
+            "description": "Operator identifier (free-form \u2014 e.g. `eq`, `contains`, `between`).",
             "example": "between"
           },
           "value": {