@talonic/docs 0.11.0 → 0.13.0

package/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Talonic API",
     "version": "1.0.0",
-    "description": "Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (≤5 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` — poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {\"async\": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` → `processing` → `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` — daily cap for the namespace\n- `X-RateLimit-Remaining` — requests left today\n- `X-RateLimit-Reset` — ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1–100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n",
+    "description": "Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (≤5 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` — poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {\"async\": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` → `processing` → `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` — daily cap for the namespace\n- `X-RateLimit-Remaining` — requests left today\n- `X-RateLimit-Reset` — ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1–100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  \"statusCode\": 400,\n  \"code\": \"VALIDATION_ERROR\",\n  \"error\": \"Bad Request\",\n  \"message\": \"name is required.\",\n  \"retryable\": false,\n  \"timestamp\": \"2026-04-25T14:30:00.000Z\",\n  \"path\": \"/v1/schemas\"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Flow\n\nDocuments ≤5 pages return results synchronously (`200`). Larger documents\n— or any request with `options: {\"async\": true}` — return `202 Accepted`.\n\n**1. Submit extraction:**\n\n```bash\ncurl -X POST https://api.talonic.com/v1/extract \\\n  -H \"Authorization: Bearer tlnc_live_abc123\" \\\n  -F \"file=@contract.pdf\" \\\n  -F 'options={\"async\": true}'\n```\n\nResponse `202`:\n```json\n{\n  \"request_id\": \"req_x7y8z9a0\",\n  \"status\": \"processing\",\n  \"document\": { \"id\": \"f0e1d2c3-b4a5-9687-8765-432109876543\" },\n  \"poll_url\": \"/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543\"\n}\n```\n\n**2. Poll until complete:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543 \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\nWhile processing: `{ \"status\": \"processing\" }`\nWhen done: `{ \"status\": \"completed\" }`\n\n**3. Retrieve results:**\n\n```bash\ncurl https://api.talonic.com/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543/extractions \\\n  -H \"Authorization: Bearer tlnc_live_abc123\"\n```\n\n**Python polling example:**\n\n```python\nimport time, requests\n\nresp = requests.post(\"https://api.talonic.com/v1/extract\",\n    headers={\"Authorization\": \"Bearer tlnc_live_abc123\"},\n    files={\"file\": open(\"contract.pdf\", \"rb\")},\n    data={\"options\": '{\"async\": true}'})\ndoc_id = resp.json()[\"document\"][\"id\"]\n\ndelay = 2\nfor _ in range(15):\n    time.sleep(delay)\n    doc = requests.get(f\"https://api.talonic.com/v1/documents/{doc_id}\",\n        headers={\"Authorization\": \"Bearer tlnc_live_abc123\"}).json()\n    if doc[\"status\"] == \"completed\":\n        break\n    delay = min(delay * 2, 30)  # 2s, 4s, 8s, 16s, 30s cap\n\nextractions = requests.get(\n    f\"https://api.talonic.com/v1/documents/{doc_id}/extractions\",\n    headers={\"Authorization\": \"Bearer tlnc_live_abc123\"}).json()\nprint(extractions[\"data\"][0][\"data\"])\n```\n\nRecommended polling: 2s initial, exponential backoff (2→4→8→16→30s cap),\ntimeout after 5 minutes.\n\n**Alternative — Webhooks:** Configure a delivery destination and listen for\n`document.extracted` events. See the Delivery tag.\n\n**Job status state machine:**\n`pending` → `queued` → `processing` → `complete` | `failed`\n\n## Performance\n\n| Document size | Expected latency | Max timeout |\n|---------------|------------------|-------------|\n| 1–5 pages     | Sync, <3s        | 30s         |\n| 6–50 pages    | <30s average     | 5 min       |\n| 50+ pages     | <5 min average   | 30 min      |\n\n**Uptime SLA:** 99.5% (Build), 99.9% (Scale), custom (Enterprise).\n\n**Max file size:** 500 MB. JSON request bodies (schemas, jobs): 1 MB.\n\n**Idempotency:** Pass `Idempotency-Key` header on POST requests. Keys are\nvalid for 24 hours and scoped per API key. Duplicates return the cached\nresponse with `cached: true`.\n",
     "contact": {
       "name": "Talonic Support",
       "email": "support@talonic.ai",
@@ -31,115 +31,39 @@
   "tags": [
     {
       "name": "Extract",
-      "description": "Upload a document and extract structured data in one call."
+      "description": "Upload a document and extract structured data in one call. Start here."
     },
     {
       "name": "Documents",
-      "description": "Browse, inspect, and delete processed documents."
+      "description": "Browse, inspect, and delete processed documents. Includes document type classification and OCR markdown retrieval."
     },
     {
       "name": "Extractions",
-      "description": "Access and correct extracted data."
+      "description": "Access extraction results, retrieve structured data in JSON or CSV, and submit field-level corrections."
     },
     {
       "name": "Schemas",
-      "description": "Create and manage reusable extraction schemas."
+      "description": "Create and manage reusable extraction schemas, schema graph classes, output dialects, and the field registry."
     },
     {
-      "name": "Jobs",
-      "description": "Track and control async processing jobs."
+      "name": "Jobs & Batches",
+      "description": "Track async processing jobs, poll for completion, retrieve result grids, and manage batch inference runs at 50% cost."
     },
     {
       "name": "Sources",
-      "description": "Manage document ingest sources and upload documents into them."
-    },
-    {
-      "name": "Dialects",
-      "description": "Manage shared dialects — named presets for output format conventions (date format, number locale, CSV delimiter, encoding, boolean rendering)."
-    },
-    {
-      "name": "Matching",
-      "description": "Reference-data matching configurations and runs. Matches extracted document fields against reference datasets with weighted field mappings."
-    },
-    {
-      "name": "Routing",
-      "description": "Document routing rules that trigger actions when classification conditions are met."
+      "description": "Create document ingest sources with dedicated API keys. Upload documents for automatic extraction."
     },
     {
       "name": "Delivery",
-      "description": "Outbound delivery. Configure destinations (seven live connectors: webhook, sftp,\ns3, azure_blob, google_drive, onedrive, google_sheets), create bindings that join\nsignal filters to deliverable types + destinations + serializers, and inspect the\nhistory/DLQ/events log. Every delivery is at-least-once with an idempotency key\non the wire.\n"
-    },
-    {
-      "name": "Filter",
-      "description": "Structured filter queries over materialised document values plus omnisearch across documents, fields, and schemas."
-    },
-    {
-      "name": "Review",
-      "description": "Queue of validation records requiring human review; supports single- and batch-action approvals/rejections."
-    },
-    {
-      "name": "Quality",
-      "description": "Ground truth datasets and benchmark runs for measuring extraction accuracy."
+      "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.\nReplay failed deliveries via `POST /v1/delivery/dlq/{id}/replay`.\n"
     },
     {
-      "name": "Batches",
-      "description": "Batch inference runs. Extraction deferred to the provider's Message Batches API at 50% cost, 48h SLA."
+      "name": "Intelligence",
+      "description": "Reference-data matching, document linking graphs, case discovery, resolution runs, N-Shot comparisons, and reference dataset management."
     },
     {
-      "name": "Cases",
-      "description": "Document clusters linked through shared entity values. Cases are discovered automatically from the linking graph."
-    },
-    {
-      "name": "Document Types",
-      "description": "Canonical document type ontology and the customer's resolved types."
-    },
-    {
-      "name": "Fields",
-      "description": "Field registry — canonical field definitions discovered across the customer's documents plus cross-schema harmonization."
-    },
-    {
-      "name": "Reference Data",
-      "description": "Uploaded reference datasets (CSV/XLSX) used by matching configurations for lookups and joins."
-    },
-    {
-      "name": "Usage",
-      "description": "Aggregate and per-document API usage accounting (tokens, costs, operation types)."
-    },
-    {
-      "name": "Resolutions",
-      "description": "Resolution runs — apply field normalization, transforms, and lookup cascades to extracted data."
-    },
-    {
-      "name": "Linking",
-      "description": "Document linking graph — link keys, document links, entity graph, classification, and backfill operations."
-    },
-    {
-      "name": "N-Shot",
-      "description": "N-Shot comparison endpoints for job runs — summary, field comparisons, overrides, and judge decisions."
-    },
-    {
-      "name": "Schema Graph",
-      "description": "Schema class ontology — versioned classes, diffs with approval workflow, edges, aliases, and visualization."
-    },
-    {
-      "name": "Structuring",
-      "description": "Structuring pipeline — validation checks, approval gates with rules, result checks, pending approvals, and delivery triggers."
-    },
-    {
-      "name": "Telemetry",
-      "description": "Aggregate structuring metrics — capture hit rate, synthesize rate, strategy distribution, and tier funnel breakdowns per schema or run."
-    },
-    {
-      "name": "Validation",
-      "description": "Golden sample management and validation runs for measuring extraction accuracy against ground truth."
-    },
-    {
-      "name": "Credits",
-      "description": "Credit balance, usage history, daily breakdown, and per-request usage log."
-    },
-    {
-      "name": "Agent",
-      "description": "Workspace context snapshot and tool discovery for the embedded AI agent."
+      "name": "Platform",
+      "description": "Usage accounting, credit balance, quality benchmarks, structuring checks, validation runs, review queue, telemetry metrics, and the embedded AI agent."
     }
   ],
   "paths": {
@@ -1052,6 +976,45 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ExtractionResponse"
+                },
+                "example": {
+                  "id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
+                  "status": "complete",
+                  "document": {
+                    "id": "f0e1d2c3-b4a5-9687-8765-432109876543",
+                    "filename": "invoice-042.pdf",
+                    "pages": 3,
+                    "type_detected": "Invoice"
+                  },
+                  "data": {
+                    "vendor_name": "Acme Corporation Ltd.",
+                    "total_amount": 1275.5,
+                    "invoice_number": "INV-2024-0042"
+                  },
+                  "confidence": {
+                    "overall": 0.96,
+                    "fields": {
+                      "vendor_name": 1,
+                      "total_amount": 1,
+                      "invoice_number": 0.99
+                    }
+                  },
+                  "locked_fields": [
+                    "vendor_name",
+                    "total_amount"
+                  ],
+                  "processing": {
+                    "duration_ms": 3420,
+                    "pages_processed": 3,
+                    "region": "eu-west"
+                  },
+                  "created_at": "2026-04-25T14:30:00.000Z",
+                  "links": {
+                    "self": "/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab",
+                    "data": "/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab/data",
+                    "document": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543",
+                    "dashboard": "https://app.talonic.com/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab"
+                  }
                 }
               }
             }
@@ -1400,7 +1363,7 @@
         "summary": "Create and queue a new job",
         "description": "Start a new grid-based job that fills a user schema from a set of\ndocuments. Provide a `schema_id` and, optionally, the specific\n`document_ids` to run against. If `document_ids` is omitted or empty,\nall `completed` documents for the customer are used.\n",
         "tags": [
-          "Jobs"
+          "Jobs & Batches"
         ],
         "requestBody": {
           "required": true,
@@ -1462,7 +1425,7 @@
         "operationId": "listJobs",
         "summary": "List jobs",
         "tags": [
-          "Jobs"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -1559,7 +1522,7 @@
         "operationId": "getJob",
         "summary": "Get a job",
         "tags": [
-          "Jobs"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -1573,6 +1536,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/JobResponse"
+                },
+                "example": {
+                  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
+                  "name": "Q1 Invoice Processing",
+                  "status": "processing",
+                  "progress": 45,
+                  "estimated_seconds_remaining": null,
+                  "schema": {
+                    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+                    "name": "Invoice Schema"
+                  },
+                  "document_count": 150,
+                  "completed_documents": 67,
+                  "grid_stats": {
+                    "total_cells": 8850,
+                    "filled": 6200,
+                    "empty": 2650,
+                    "fill_rate": 0.7
+                  },
+                  "current_phase": "phase_2_execute",
+                  "created_at": "2026-04-25T14:30:00.000Z",
+                  "started_at": "2026-04-25T14:30:05.000Z",
+                  "completed_at": null,
+                  "links": {
+                    "self": "/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012",
+                    "cancel": "/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012/cancel",
+                    "dashboard": "https://app.talonic.com/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012"
+                  }
                 }
               }
             }
@@ -1595,7 +1586,7 @@
         "summary": "Cancel a job",
         "description": "Cancel a pending or processing job. Jobs that are already `complete` or\n`failed` cannot be cancelled and will return a 409 Conflict.\n",
         "tags": [
-          "Jobs"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -1637,7 +1628,7 @@
         "summary": "Get job result rows",
         "description": "Return the extracted values for every document processed by this job,\none row per document. Includes per-row confidence and any validation\nflags raised during Phase 4.\n",
         "tags": [
-          "Jobs"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -1725,6 +1716,10 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SourceCreateRequest"
+              },
+              "example": {
+                "name": "Invoice Pipeline",
+                "default_schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
               }
             }
           }
@@ -1750,6 +1745,24 @@
                       }
                     }
                   ]
+                },
+                "example": {
+                  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+                  "name": "Invoice Pipeline",
+                  "type": "api",
+                  "status": "active",
+                  "document_count": 0,
+                  "default_schema": {
+                    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
+                  },
+                  "endpoint": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
+                  "api_key": "tlnc_live_src_k8m2n4p6q9r1s3t5",
+                  "created_at": "2026-04-25T14:30:00.000Z",
+                  "links": {
+                    "self": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+                    "documents": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
+                    "dashboard": "https://app.talonic.com/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+                  }
                 }
               }
             }
@@ -2034,7 +2047,7 @@
         "summary": "List dialects",
         "description": "Return every shared dialect defined for the authenticated customer.",
         "tags": [
-          "Dialects"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -2079,7 +2092,7 @@
         "summary": "Create a dialect",
         "description": "Create a new shared dialect.",
         "tags": [
-          "Dialects"
+          "Schemas"
         ],
         "requestBody": {
           "required": true,
@@ -2129,7 +2142,7 @@
         "operationId": "getDialect",
         "summary": "Get a dialect",
         "tags": [
-          "Dialects"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -2163,7 +2176,7 @@
         "summary": "Update a dialect",
         "description": "Partial update. Only the keys present on the body are patched. Bumps the stored `version`.",
         "tags": [
-          "Dialects"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -2209,7 +2222,7 @@
         "operationId": "deleteDialect",
         "summary": "Delete a dialect",
         "tags": [
-          "Dialects"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -2250,7 +2263,7 @@
         "operationId": "listMatchingConfigs",
         "summary": "List matching configurations",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2313,7 +2326,7 @@
         "summary": "Create a matching configuration",
         "description": "Link a reference dataset to a target scope via weighted field mappings.\nThe reference dataset must belong to the authenticated customer.\n",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -2366,7 +2379,7 @@
         "operationId": "getMatchingConfig",
         "summary": "Get a matching configuration",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2400,7 +2413,7 @@
         "summary": "Update a matching configuration",
         "description": "Partial update — only provided keys are applied.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2446,7 +2459,7 @@
         "operationId": "deleteMatchingConfig",
         "summary": "Delete a matching configuration",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2488,7 +2501,7 @@
         "summary": "Trigger a matching run",
         "description": "Queue a new matching run for this configuration. The run is processed\nasynchronously; poll `GET /v1/matching/runs/{id}` for status.\n",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2534,7 +2547,7 @@
         "summary": "List matching runs",
         "description": "Returns up to the 100 most recent matching runs for the authenticated\ncustomer, optionally filtered by `config_id`. This endpoint is not\ncursor-paginated.\n",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2582,7 +2595,7 @@
         "summary": "Get a matching run",
         "description": "Returns the run summary together with up to the 50 top-confidence match results.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2618,7 +2631,7 @@
         "summary": "Cancel a matching run",
         "description": "Cancel a queued or running matching run. Runs already in a terminal\nstate (`completed`, `failed`, `cancelled`) return 400.\n",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -2657,7 +2670,7 @@
         "summary": "List routing rules",
         "description": "Paginated list of document routing rules, ordered by priority ascending (lowest runs first).",
         "tags": [
-          "Routing"
+          "Delivery"
         ],
         "parameters": [
           {
@@ -2720,7 +2733,7 @@
         "summary": "Create a routing rule",
         "description": "Create a rule that fires on `document_classified` triggers. The\n`actions.type` key (when present) controls the action kind\n(`route_to_schema` by default).\n",
         "tags": [
-          "Routing"
+          "Delivery"
         ],
         "requestBody": {
           "required": true,
@@ -2770,7 +2783,7 @@
         "operationId": "getRoutingRule",
         "summary": "Get a routing rule",
         "tags": [
-          "Routing"
+          "Delivery"
         ],
         "parameters": [
           {
@@ -2804,7 +2817,7 @@
         "summary": "Update a routing rule",
         "description": "Partial update; only provided keys are patched.",
         "tags": [
-          "Routing"
+          "Delivery"
         ],
         "parameters": [
           {
@@ -2850,7 +2863,7 @@
         "operationId": "deleteRoutingRule",
         "summary": "Delete a routing rule",
         "tags": [
-          "Routing"
+          "Delivery"
         ],
         "parameters": [
           {
@@ -4214,7 +4227,7 @@
         "summary": "Filter documents with structured conditions",
         "description": "Query documents using an ordered list of filter conditions against\nmaterialised field values. Optional free-text `search` applies\nalongside the structured filter. `limit` is clamped to a server-side\nmaximum of 500.\n",
         "tags": [
-          "Filter"
+          "Delivery"
         ],
         "requestBody": {
           "required": true,
@@ -4266,7 +4279,7 @@
         "summary": "Omnisearch across documents, fields, and schemas",
         "description": "Full-text search that returns multiple result collections in a single\nresponse: matching documents, field matches, sources, schemas, and\nfields.\n",
         "tags": [
-          "Filter"
+          "Delivery"
         ],
         "parameters": [
           {
@@ -4315,7 +4328,7 @@
         "summary": "List review queue records",
         "description": "Paginated list of validation records awaiting or having completed review.",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4388,7 +4401,7 @@
         "summary": "Apply a review action to many records",
         "description": "Approve or reject many validation records in one call. Failed ids\n(not found or not owned by the customer) are reported in the\n`results` array rather than aborting the whole batch.\n",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -4429,7 +4442,7 @@
         "summary": "Get a review record",
         "description": "Returns the full record including per-field decisions and low-confidence field list.",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4464,7 +4477,7 @@
         "operationId": "performReviewAction",
         "summary": "Approve or reject a review record",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4512,7 +4525,7 @@
         "operationId": "listGroundTruthDatasets",
         "summary": "List ground truth datasets",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4574,7 +4587,7 @@
         "operationId": "createGroundTruthDataset",
         "summary": "Create a ground truth dataset",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -4625,7 +4638,7 @@
         "summary": "Get a ground truth dataset",
         "description": "Returns the dataset together with its sample entries (curated known-correct values).",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4660,7 +4673,7 @@
         "operationId": "listBenchmarkRuns",
         "summary": "List benchmark runs",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4725,7 +4738,7 @@
         "summary": "Get a benchmark run",
         "description": "Returns the benchmark run together with its per-document results.",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -4761,7 +4774,7 @@
         "summary": "List batch inference runs",
         "description": "Documents uploaded with `processing_mode=batch` accumulate in an\n`ExtractionBatch` and are submitted to the provider (Anthropic or\nBedrock) at 50% of the realtime cost with a 48h SLA. This endpoint\nreturns a paginated list of the customer's batches.\n",
         "tags": [
-          "Batches"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -4831,7 +4844,7 @@
         "summary": "Get a batch inference run",
         "description": "Returns the batch metadata plus per-item status for every document in the batch.",
         "tags": [
-          "Batches"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -4867,7 +4880,7 @@
         "summary": "List cases",
         "description": "Cases are document clusters discovered automatically from shared entity values across documents (BFS on the linking graph; inference mode may materialise them as first-class entities).",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -4922,7 +4935,7 @@
         "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",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -4968,7 +4981,7 @@
         "summary": "List document types",
         "description": "Document types resolved for the authenticated customer, ordered by document count descending.",
         "tags": [
-          "Document Types"
+          "Documents"
         ],
         "responses": {
           "200": {
@@ -5004,7 +5017,7 @@
         "summary": "Get the document type ontology",
         "description": "Returns the canonical category summary (categories, subcategories, and types) used by the classifier.",
         "tags": [
-          "Document Types"
+          "Documents"
         ],
         "responses": {
           "200": {
@@ -5042,7 +5055,7 @@
         "summary": "List fields",
         "description": "Paginated list of fields from the field registry, filterable by search, tier, or cluster.",
         "tags": [
-          "Fields"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -5122,7 +5135,7 @@
         "summary": "Cross-schema field overlap",
         "description": "Fields appearing in two or more schemas, grouped by `canonical_name`.\nUsed to reconcile field definitions across schemas (a field marked\n`is_universal: true` appears in every schema).\n",
         "tags": [
-          "Fields"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -5158,7 +5171,7 @@
         "summary": "Get a field",
         "description": "Returns the field registry row plus up to 20 most recent occurrences.",
         "tags": [
-          "Fields"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -5194,7 +5207,7 @@
         "summary": "Get fields similar to this one",
         "description": "Returns up to 10 fields most similar to this one by cosine similarity\non the `name_embedding` vector (all-MiniLM-L6-v2, 384 dims). Returns\nan empty `data` array if the field has no embedding computed yet.\n",
         "tags": [
-          "Fields"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -5274,7 +5287,7 @@
         "summary": "List reference datasets",
         "description": "Uploaded reference datasets (CSV/XLSX) available for matching configurations.",
         "tags": [
-          "Reference Data"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -5309,7 +5322,7 @@
         "operationId": "getReferenceData",
         "summary": "Get a reference dataset",
         "tags": [
-          "Reference Data"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5342,7 +5355,7 @@
         "operationId": "deleteReferenceData",
         "summary": "Delete a reference dataset",
         "tags": [
-          "Reference Data"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5383,7 +5396,7 @@
         "summary": "Get reference dataset rows (paginated)",
         "description": "Returns the dataset's rows, paginated with page/limit (limit capped at 500).",
         "tags": [
-          "Reference Data"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5462,7 +5475,7 @@
         "summary": "Aggregate API usage stats",
         "description": "Returns token and call counts aggregated by `operation_type` and\n`model` over the requested date range. Default range is the last 30\ndays.\n",
         "tags": [
-          "Usage"
+          "Platform"
         ],
         "parameters": [
           {
@@ -5510,7 +5523,7 @@
         "summary": "Per-document API usage",
         "description": "Returns per-document API usage entries and totals. 404 if no usage records exist for the document.",
         "tags": [
-          "Usage"
+          "Platform"
         ],
         "parameters": [
           {
@@ -5545,7 +5558,7 @@
         "operationId": "listResolutions",
         "summary": "List resolution runs",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5597,7 +5610,7 @@
         "summary": "Create a resolution run",
         "description": "Start a new resolution run targeting documents from a specific source run.",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -5648,7 +5661,7 @@
         "operationId": "getResolution",
         "summary": "Get a resolution run",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5681,7 +5694,7 @@
         "operationId": "deleteResolution",
         "summary": "Delete a resolution run",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5717,7 +5730,7 @@
         "summary": "Get resolution run results",
         "description": "Returns the resolved data for all documents in the resolution run.",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5762,7 +5775,7 @@
         "summary": "Execute a resolution run",
         "description": "Trigger execution of a pending resolution run.",
         "tags": [
-          "Resolutions"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5798,7 +5811,7 @@
         "summary": "List link keys",
         "description": "Returns all configured link keys (field-level entity identifiers used for document linking).",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -5834,7 +5847,7 @@
         "summary": "Get links for a document",
         "description": "Returns all entity links discovered for a specific document.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5897,7 +5910,7 @@
         "summary": "Get the full linking graph",
         "description": "Returns the bipartite document-entity graph for the customer.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -5941,7 +5954,7 @@
         "summary": "Get graph neighbourhood for a document",
         "description": "Returns the subgraph of entities and linked documents for a specific document.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -5993,7 +6006,7 @@
         "summary": "Classify link keys",
         "description": "Run AI classification on ambiguous fields to determine their link key category (identity, transaction, reference).",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -6033,7 +6046,7 @@
         "summary": "Backfill linking data",
         "description": "Trigger a backfill of the linking graph for all documents. Useful after link key configuration changes.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "202": {
@@ -6071,7 +6084,7 @@
         "summary": "Get backfill progress",
         "description": "Returns the current progress of an in-flight backfill operation.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -6116,7 +6129,7 @@
         "summary": "Get document-to-case mapping",
         "description": "Returns a mapping of document IDs to their assigned case keys.",
         "tags": [
-          "Linking"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -6153,7 +6166,7 @@
         "summary": "Get N-Shot summary for a run",
         "description": "Returns an aggregate summary of N-Shot comparisons for a job run.",
         "tags": [
-          "N-Shot"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -6198,7 +6211,7 @@
         "summary": "List N-Shot comparisons",
         "description": "Returns all N-Shot comparisons for a job run.",
         "tags": [
-          "N-Shot"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -6251,7 +6264,7 @@
         "summary": "Get a specific N-Shot comparison",
         "description": "Returns a single N-Shot comparison filtered by document and field.",
         "tags": [
-          "N-Shot"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -6316,7 +6329,7 @@
         "summary": "Override an N-Shot value",
         "description": "Manually override the N-Shot selected value for a document-field pair.",
         "tags": [
-          "N-Shot"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -6397,7 +6410,7 @@
         "summary": "Submit a judge decision for N-Shot",
         "description": "Submit an AI or human judge decision on which N-Shot candidate is correct.",
         "tags": [
-          "N-Shot"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -6479,7 +6492,7 @@
         "summary": "List schema graph classes",
         "description": "Returns all classes in the schema graph ontology.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -6514,7 +6527,7 @@
         "operationId": "getSchemaGraphClass",
         "summary": "Get a schema graph class",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -6550,7 +6563,7 @@
         "summary": "List versions of a schema graph class",
         "description": "Returns all published versions of a class, ordered by version number descending.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -6610,7 +6623,7 @@
         "operationId": "getSchemaGraphClassVersion",
         "summary": "Get a specific version of a schema graph class",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -6672,7 +6685,7 @@
         "summary": "List schema graph diffs",
         "description": "Returns pending and processed diffs between class versions.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -6708,7 +6721,7 @@
         "summary": "Approve a schema graph diff",
         "description": "Approve a pending diff, promoting the changes to the live class version.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -6744,7 +6757,7 @@
         "summary": "Reject a schema graph diff",
         "description": "Reject a pending diff, discarding the proposed changes.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "parameters": [
           {
@@ -6780,7 +6793,7 @@
         "summary": "List schema graph edges",
         "description": "Returns all edges (relationships) between schema graph classes.",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -6835,7 +6848,7 @@
         "summary": "List schema graph aliases",
         "description": "Returns all class aliases (alternative names mapping to canonical class IDs).",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -6884,7 +6897,7 @@
         "summary": "Get schema graph visualization data",
         "description": "Returns nodes and edges formatted for graph visualization (D3-compatible).",
         "tags": [
-          "Schema Graph"
+          "Schemas"
         ],
         "responses": {
           "200": {
@@ -6928,7 +6941,7 @@
         "summary": "List structuring checks",
         "description": "Returns all configured validation checks for the customer.",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -6979,7 +6992,7 @@
         "operationId": "createStructuringCheck",
         "summary": "Create a structuring check",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -7019,7 +7032,7 @@
         "operationId": "getStructuringCheck",
         "summary": "Get a structuring check",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7052,7 +7065,7 @@
         "operationId": "updateStructuringCheck",
         "summary": "Update a structuring check",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7098,7 +7111,7 @@
         "operationId": "deleteStructuringCheck",
         "summary": "Delete a structuring check",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7134,7 +7147,7 @@
         "summary": "List approval gates",
         "description": "Returns all configured approval gates for the customer.",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7185,7 +7198,7 @@
         "operationId": "createStructuringGate",
         "summary": "Create an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -7225,7 +7238,7 @@
         "operationId": "getStructuringGate",
         "summary": "Get an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7258,7 +7271,7 @@
         "operationId": "updateStructuringGate",
         "summary": "Update an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7304,7 +7317,7 @@
         "operationId": "deleteStructuringGate",
         "summary": "Delete an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7339,7 +7352,7 @@
         "operationId": "addStructuringGateRule",
         "summary": "Add a rule to an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7400,7 +7413,7 @@
         "operationId": "deleteStructuringGateRule",
         "summary": "Remove a rule from an approval gate",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7456,7 +7469,7 @@
         "summary": "Get check results for a structuring result",
         "description": "Returns the validation check outcomes for a specific structuring result.",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7519,7 +7532,7 @@
         "summary": "List pending approvals",
         "description": "Returns structuring results awaiting manual approval.",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7570,7 +7583,7 @@
         "operationId": "approveStructuringResult",
         "summary": "Approve a structuring result",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7616,7 +7629,7 @@
         "operationId": "rejectStructuringResult",
         "summary": "Reject a structuring result",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7663,7 +7676,7 @@
         "summary": "Trigger delivery for a structuring run",
         "description": "Emit delivery signals for all approved results in the run.",
         "tags": [
-          "Structuring"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7715,7 +7728,7 @@
         "summary": "Get telemetry summary for a schema",
         "description": "Aggregate structuring metrics for a schema — capture hit rate, synthesize rate, strategy distribution, tier funnel.",
         "tags": [
-          "Telemetry"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7752,7 +7765,7 @@
         "summary": "Get telemetry trend for a schema",
         "description": "Time-series telemetry data for a schema over recent runs.",
         "tags": [
-          "Telemetry"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7797,7 +7810,7 @@
         "summary": "Get per-field telemetry for a schema",
         "description": "Field-level structuring metrics — per-field state distribution, capture rates, and strategy breakdown.",
         "tags": [
-          "Telemetry"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7842,7 +7855,7 @@
         "summary": "Get telemetry summary for a run",
         "description": "Aggregate structuring metrics for a specific job run.",
         "tags": [
-          "Telemetry"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7879,7 +7892,7 @@
         "summary": "List golden samples",
         "description": "Returns all golden sample datasets for the customer.",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7932,7 +7945,7 @@
         "operationId": "getGoldenSample",
         "summary": "Get a golden sample",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -7965,7 +7978,7 @@
         "operationId": "deleteGoldenSample",
         "summary": "Delete a golden sample",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8000,7 +8013,7 @@
         "operationId": "listValidationRuns",
         "summary": "List validation runs",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8052,7 +8065,7 @@
         "summary": "Create a validation run",
         "description": "Start a new validation run against a golden sample dataset.",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -8109,7 +8122,7 @@
         "operationId": "getValidationRun",
         "summary": "Get a validation run",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8142,7 +8155,7 @@
         "operationId": "deleteValidationRun",
         "summary": "Delete a validation run",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8178,7 +8191,7 @@
         "summary": "Get validation run results",
         "description": "Returns per-document and per-field accuracy results for the validation run.",
         "tags": [
-          "Validation"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8234,7 +8247,7 @@
         "summary": "Get credit balance",
         "description": "Returns the current credit balance for the authenticated customer.",
         "tags": [
-          "Credits"
+          "Platform"
         ],
         "responses": {
           "200": {
@@ -8281,7 +8294,7 @@
         "summary": "Get credit history",
         "description": "Returns credit transaction history (purchases, deductions, adjustments).",
         "tags": [
-          "Credits"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8361,7 +8374,7 @@
         "summary": "Get credit usage summary",
         "description": "Returns aggregate credit usage broken down by feature.",
         "tags": [
-          "Credits"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8433,7 +8446,7 @@
         "summary": "Get daily credit usage",
         "description": "Returns per-day credit usage for the specified period (default last 30 days).",
         "tags": [
-          "Credits"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8502,7 +8515,7 @@
         "summary": "Get credit usage log",
         "description": "Returns a detailed per-request usage log with model, tokens, and cost.",
         "tags": [
-          "Credits"
+          "Platform"
         ],
         "parameters": [
           {
@@ -8581,7 +8594,7 @@
         "operationId": "updateCaseStatus",
         "summary": "Update case status",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -8646,7 +8659,7 @@
         "summary": "Get case edges",
         "description": "Returns the entity edges (evidence chain) connecting documents within the case.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -8718,7 +8731,7 @@
         "summary": "Confirm a case edge",
         "description": "Confirm a proposed entity edge between documents.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -8784,7 +8797,7 @@
         "summary": "Reject a case edge",
         "description": "Reject a proposed entity edge between documents.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -8850,7 +8863,7 @@
         "summary": "Split a case",
         "description": "Split a case into two separate cases by dividing documents.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -8927,7 +8940,7 @@
         "summary": "Merge cases",
         "description": "Merge another case into this one, combining all documents.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -8991,7 +9004,7 @@
         "summary": "Get case completeness",
         "description": "Returns a completeness assessment for the case (expected vs. present document types, missing fields).",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9057,7 +9070,7 @@
         "summary": "Pin documents to a case",
         "description": "Manually pin one or more documents to a case.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9125,7 +9138,7 @@
         "summary": "Remove documents from a case",
         "description": "Remove one or more manually-pinned documents from a case.",
         "tags": [
-          "Cases"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9193,7 +9206,7 @@
         "summary": "Sync batch status with provider",
         "description": "Force a status sync with the batch inference provider (Anthropic or Bedrock).",
         "tags": [
-          "Batches"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -9229,7 +9242,7 @@
         "summary": "Cancel a batch inference run",
         "description": "Cancel an in-flight batch. Only batches in `accumulating` or `submitted` status can be cancelled.",
         "tags": [
-          "Batches"
+          "Jobs & Batches"
         ],
         "parameters": [
           {
@@ -9268,7 +9281,7 @@
         "summary": "Trigger a smart matching run",
         "description": "AI-driven matching run that auto-suggests field mappings and strategies based on schema and reference data.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -9323,7 +9336,7 @@
         "summary": "AI-resolve ambiguous matches",
         "description": "Use AI to resolve ambiguous match candidates where confidence is below the auto-accept threshold.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -9386,7 +9399,7 @@
         "summary": "List matching strategies",
         "description": "Returns available matching strategies and their configurations.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "responses": {
           "200": {
@@ -9436,7 +9449,7 @@
         "operationId": "createMatchingStrategy",
         "summary": "Create a matching strategy",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -9495,7 +9508,7 @@
         "operationId": "getMatchingStrategy",
         "summary": "Get a matching strategy",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9529,7 +9542,7 @@
         "operationId": "updateMatchingStrategy",
         "summary": "Update a matching strategy",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9585,7 +9598,7 @@
         "operationId": "deleteMatchingStrategy",
         "summary": "Delete a matching strategy",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9621,7 +9634,7 @@
         "summary": "Get matching run results",
         "description": "Returns per-document match results with top candidates and field-level evidence.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9666,7 +9679,7 @@
         "summary": "Get matching run progress",
         "description": "Returns the processing progress for an in-flight matching run.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "parameters": [
           {
@@ -9718,7 +9731,7 @@
         "summary": "Submit matching review decisions",
         "description": "Submit accept/reject decisions on match candidates.",
         "tags": [
-          "Matching"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -9800,7 +9813,7 @@
         "summary": "Assign review records",
         "description": "Assign one or more review records to a team member.",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "requestBody": {
           "required": true,
@@ -9866,7 +9879,7 @@
         "summary": "Get review queue statistics",
         "description": "Returns aggregate statistics about the review queue (pending, approved, rejected counts).",
         "tags": [
-          "Review"
+          "Platform"
         ],
         "responses": {
           "200": {
@@ -9907,7 +9920,7 @@
         "operationId": "listGroundTruthEntries",
         "summary": "List entries in a ground truth dataset",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -9961,7 +9974,7 @@
         "operationId": "createGroundTruthEntry",
         "summary": "Add an entry to a ground truth dataset",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -10027,7 +10040,7 @@
         "operationId": "updateGroundTruthEntry",
         "summary": "Update a ground truth entry",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -10091,7 +10104,7 @@
         "operationId": "deleteGroundTruthEntry",
         "summary": "Delete a ground truth entry",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -10138,7 +10151,7 @@
         "summary": "Get benchmark results",
         "description": "Returns per-document accuracy results for a benchmark run.",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -10182,7 +10195,7 @@
         "summary": "Compare two benchmark runs",
         "description": "Returns accuracy deltas between the target benchmark and a comparison run.",
         "tags": [
-          "Quality"
+          "Platform"
         ],
         "parameters": [
           {
@@ -10254,7 +10267,7 @@
         "summary": "Create reference data from JSON",
         "description": "Create a new reference dataset by uploading JSON data directly (alternative to CSV/XLSX file upload).",
         "tags": [
-          "Reference Data"
+          "Intelligence"
         ],
         "requestBody": {
           "required": true,
@@ -10320,7 +10333,7 @@
         "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",
         "tags": [
-          "Agent"
+          "Platform"
         ],
         "responses": {
           "200": {
@@ -10375,7 +10388,7 @@
         "summary": "List available agent tools",
         "description": "Returns the set of tools the embedded AI agent can invoke in the\ncurrent workspace, including their names, descriptions, parameter\nschemas, and tier requirements.\n",
         "tags": [
-          "Agent"
+          "Platform"
         ],
         "responses": {
           "200": {
@@ -10524,8 +10537,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "validation_error",
-              "message": "name is required."
+              "statusCode": 400,
+              "code": "VALIDATION_ERROR",
+              "error": "Bad Request",
+              "message": "name is required.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/schemas"
             }
           }
         }
@@ -10538,8 +10556,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "unauthorized",
-              "message": "Invalid or missing API key."
+              "statusCode": 401,
+              "code": "AUTH_REQUIRED",
+              "error": "Unauthorized",
+              "message": "Invalid or missing API key.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/extract"
             }
           }
         }
@@ -10552,8 +10575,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "insufficient_scope",
-              "message": "This key does not have the 'write' scope."
+              "statusCode": 403,
+              "code": "INSUFFICIENT_PERMISSIONS",
+              "error": "Forbidden",
+              "message": "This key does not have the 'write' scope.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/schemas"
             }
           }
         }
@@ -10566,8 +10594,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "not_found",
-              "message": "Document 'abc-123' not found."
+              "statusCode": 404,
+              "code": "RESOURCE_NOT_FOUND",
+              "error": "Not Found",
+              "message": "Document 'f0e1d2c3-b4a5-9687-8765-432109876543' not found.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543"
             }
           }
         }
@@ -10580,8 +10613,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "conflict",
-              "message": "Job is already completed. Cannot cancel."
+              "statusCode": 409,
+              "code": "VALIDATION_ERROR",
+              "error": "Conflict",
+              "message": "Job is already completed. Cannot cancel.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012/cancel"
             }
           }
         }
@@ -10594,8 +10632,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "payload_too_large",
-              "message": "File exceeds the 500 MB limit."
+              "statusCode": 413,
+              "code": "FILE_TOO_LARGE",
+              "error": "Payload Too Large",
+              "message": "File exceeds the 500 MB limit.",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/extract"
             }
           }
         }
@@ -10608,9 +10651,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "extraction_failed",
+              "statusCode": 422,
+              "code": "EXTRACTION_FAILED",
+              "error": "Unprocessable Entity",
               "message": "Unable to extract fields from the provided document.",
-              "request_id": "req_abc123",
+              "retryable": false,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/extract",
               "links": {
                 "dashboard": "https://app.talonic.com/documents/abc-123"
               }
@@ -10637,11 +10684,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "rate_limit_exceeded",
+              "statusCode": 429,
+              "code": "QUOTA_EXCEEDED",
+              "error": "Too Many Requests",
               "message": "Daily extract request limit (50) reached. Resets at midnight UTC.",
-              "limit": 50,
-              "used": 50,
-              "reset_at": "2026-04-05T00:00:00.000Z"
+              "retryable": true,
+              "timestamp": "2026-04-25T23:45:00.000Z",
+              "path": "/v1/extract"
             }
           }
         }
@@ -10654,9 +10703,13 @@
               "$ref": "#/components/schemas/ErrorResponse"
             },
             "example": {
-              "error": "internal_error",
+              "statusCode": 500,
+              "code": "INTERNAL_ERROR",
+              "error": "Internal Server Error",
               "message": "An unexpected error occurred. Please try again or contact support.",
-              "request_id": "req_xyz789"
+              "retryable": true,
+              "timestamp": "2026-04-25T14:30:00.000Z",
+              "path": "/v1/extract"
             }
           }
         }
@@ -10666,29 +10719,143 @@
       "ErrorResponse": {
         "type": "object",
         "required": [
+          "statusCode",
+          "code",
           "error",
-          "message"
+          "message",
+          "retryable",
+          "timestamp",
+          "path"
         ],
         "properties": {
+          "statusCode": {
+            "type": "integer",
+            "description": "HTTP status code.",
+            "example": 400
+          },
+          "code": {
+            "type": "string",
+            "description": "Machine-readable error discriminant. One of: VALIDATION_ERROR,\nAUTH_REQUIRED, TOKEN_EXPIRED, INSUFFICIENT_PERMISSIONS,\nRESOURCE_NOT_FOUND, QUOTA_EXCEEDED, INSUFFICIENT_CREDITS,\nLLM_RATE_LIMITED, LLM_TIMEOUT, LLM_UNAVAILABLE, OCR_FAILED,\nEXTRACTION_FAILED, EXTRACTION_TIMEOUT, FILE_TOO_LARGE,\nDUPLICATE_RESOURCE, DATASPACE_RUN_FAILED, INTERNAL_ERROR.\n",
+            "example": "VALIDATION_ERROR"
+          },
           "error": {
             "type": "string",
-            "description": "Machine-readable error code."
+            "description": "HTTP status name.",
+            "example": "Bad Request"
           },
           "message": {
             "type": "string",
-            "example": "Re-extraction started.",
-            "description": "Human-readable error description."
+            "description": "Human-readable error description.",
+            "example": "name is required."
           },
-          "request_id": {
+          "retryable": {
+            "type": "boolean",
+            "description": "Whether the client should retry the request.",
+            "example": false
+          },
+          "timestamp": {
             "type": "string",
-            "description": "Request ID for support reference."
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when the error occurred.",
+            "example": "2026-04-25T14:30:00.000Z"
           },
-          "links": {
+          "path": {
+            "type": "string",
+            "description": "Request path that failed.",
+            "example": "/v1/schemas"
+          }
+        }
+      },
+      "WebhookEvent": {
+        "type": "object",
+        "description": "Webhook delivery payload sent to configured destinations.",
+        "required": [
+          "event"
+        ],
+        "properties": {
+          "event": {
             "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Related resource links."
+            "required": [
+              "event_type",
+              "event_id",
+              "binding_id",
+              "idempotency_key",
+              "attempt",
+              "delivered_at"
+            ],
+            "properties": {
+              "event_type": {
+                "type": "string",
+                "description": "The event that triggered this delivery. One of:\ndocument.extracted, document.extraction_failed,\nrun.dataspace.completed, run.dataspace.failed,\nresult.dataspace.completed, result.dataspace.failed,\nrun.structuring.completed, run.structuring.failed,\nrun.resolution.completed, run.resolution.failed,\nrun.extraction.completed, run.extraction.failed,\nresult.flagged, result.approved, result.rejected,\ndelivery.item.completed, delivery.item.failed.\n",
+                "example": "document.extracted"
+              },
+              "event_id": {
+                "type": "string",
+                "description": "Monotonically increasing event sequence ID.",
+                "example": "42"
+              },
+              "binding_id": {
+                "type": "string",
+                "format": "uuid",
+                "description": "The delivery binding that matched this event.",
+                "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+              },
+              "idempotency_key": {
+                "type": "string",
+                "description": "32-character hex key derived from binding_id + event_id. Stable across retries.",
+                "example": "c9f3a7e1b2d4f6a8e0c2d4f6a8e0c2d4"
+              },
+              "attempt": {
+                "type": "integer",
+                "description": "Delivery attempt number (1–7).",
+                "example": 1
+              },
+              "delivered_at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Timestamp of this delivery attempt.",
+                "example": "2026-04-25T14:30:00.000Z"
+              }
+            }
+          },
+          "payload": {
+            "type": "object",
+            "description": "Serialized deliverable data. Shape depends on the deliverable type and serializer format configured on the binding.",
+            "additionalProperties": true,
+            "example": {
+              "document_id": "f0e1d2c3-b4a5-9687-8765-432109876543",
+              "filename": "invoice-042.pdf",
+              "status": "completed",
+              "data": {
+                "invoice_number": "INV-2024-0042",
+                "total_amount": 1250
+              }
+            }
+          },
+          "content": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Binary content envelope (for file-type serializers like CSV/XLSX). Null when payload is used instead.",
+            "properties": {
+              "mime": {
+                "type": "string",
+                "example": "text/csv"
+              },
+              "encoding": {
+                "type": "string",
+                "enum": [
+                  "utf-8",
+                  "base64"
+                ],
+                "example": "utf-8"
+              },
+              "data": {
+                "type": "string",
+                "description": "UTF-8 text or base64-encoded binary."
+              }
+            }
           }
         }
       },