@talonic/docs 0.11.0 → 0.12.0

package/dist/seo.js

@@ -4,7 +4,7 @@ var openapi_default = {
   info: {
     title: "Talonic API",
     version: "1.0.0",
-    description: 'Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (\u22645 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` \u2014 poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {"async": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` \u2014 daily cap for the namespace\n- `X-RateLimit-Remaining` \u2014 requests left today\n- `X-RateLimit-Reset` \u2014 ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1\u2013100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n',
+    description: 'Structure any document into schema-validated data.\n\nThe Talonic API lets you extract structured data from documents (PDFs, images,\nDOCX, CSV, plain text), manage reusable extraction schemas, track async jobs,\nand organise documents through sources.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nAPI keys are prefixed with `tlnc_` and scoped per customer.\n\n```\nAuthorization: Bearer tlnc_live_abc123...\n```\n\n## Async Extraction Pattern\n\nSmall documents (\u22645 pages) are processed synchronously and return a `200`\nwith the extracted data immediately. Larger documents return a `202 Accepted`\nwith a `poll_url` \u2014 poll `GET /v1/documents/{id}` until `status` transitions\nto `completed`, then fetch results via `GET /v1/documents/{id}/extractions`.\n\nYou can force async processing by passing `options: {"async": true}` on\nany extraction request. Combine with webhooks for a fully event-driven flow:\nconfigure a webhook destination under Delivery and listen for the\n`extraction.complete` event.\n\n**Job status lifecycle:** `pending` \u2192 `processing` \u2192 `complete` | `failed`\n\n## Rate Limits\n\nRequests are metered per calendar day (UTC). Limits depend on your plan tier:\n\n| Tier       | Extract | Platform | Ingest |\n|------------|---------|----------|--------|\n| Free       | 50/day  | 500/day  | 50/day |\n| Pro        | 2,000   | 10,000   | 2,000  |\n| Enterprise | Unlimited | Unlimited | Unlimited |\n\nEvery response includes rate-limit headers:\n- `X-RateLimit-Limit` \u2014 daily cap for the namespace\n- `X-RateLimit-Remaining` \u2014 requests left today\n- `X-RateLimit-Reset` \u2014 ISO 8601 timestamp when the window resets (midnight UTC)\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `limit` (1\u2013100, default 20),\n`cursor` (opaque token from `pagination.next_cursor`), and `order` (`asc` or `desc`, default `desc`).\n\n## Errors\n\nAll errors return a JSON body with `error` (machine-readable code) and `message`\n(human-readable explanation). Additional fields vary by error type.\n\n| Code | Error              | Description                              |\n|------|--------------------|------------------------------------------|\n| 400  | validation_error   | Request body is malformed or invalid     |\n| 401  | unauthorized       | Missing or invalid API key               |\n| 403  | insufficient_scope | API key lacks the required scope         |\n| 404  | not_found          | Resource does not exist                  |\n| 409  | conflict           | Resource state conflict                  |\n| 413  | payload_too_large  | File exceeds 500 MB limit                |\n| 422  | extraction_failed  | Document could not be processed          |\n| 429  | rate_limit_exceeded| Daily rate limit reached                 |\n| 500  | internal_error     | Unexpected server error (retryable)      |\n\nEvery error response follows this envelope:\n\n```json\n{\n  "statusCode": 400,\n  "code": "VALIDATION_ERROR",\n  "error": "Bad Request",\n  "message": "name is required.",\n  "retryable": false,\n  "timestamp": "2026-04-25T14:30:00.000Z",\n  "path": "/v1/schemas"\n}\n```\n\nThe `code` field is one of: `VALIDATION_ERROR`, `AUTH_REQUIRED`, `TOKEN_EXPIRED`,\n`INSUFFICIENT_PERMISSIONS`, `RESOURCE_NOT_FOUND`, `QUOTA_EXCEEDED`,\n`INSUFFICIENT_CREDITS`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_UNAVAILABLE`,\n`OCR_FAILED`, `EXTRACTION_FAILED`, `EXTRACTION_TIMEOUT`, `FILE_TOO_LARGE`,\n`DUPLICATE_RESOURCE`, `DATASPACE_RUN_FAILED`, `INTERNAL_ERROR`.\n\n## Async Extraction Lifecycle\n\nEnd-to-end async flow:\n\n**Step 1 \u2014 Submit extraction with `async: true`:**\n```\nPOST /v1/extract\nContent-Type: multipart/form-data\nAuthorization: Bearer tlnc_live_abc123\n\nfile=@contract.pdf\noptions={"async": true}\n```\nResponse `202 Accepted`:\n```json\n{\n  "request_id": "req_x7y8z9a0",\n  "status": "processing",\n  "document": { "id": "f0e1d2c3-..." },\n  "poll_url": "/v1/documents/f0e1d2c3-..."\n}\n```\n\n**Step 2 \u2014 Poll for completion:**\n```\nGET /v1/documents/f0e1d2c3-...\n```\nResponse `200` (when done): `"status": "completed"`\n\n**Step 3 \u2014 Retrieve results:**\n```\nGET /v1/documents/f0e1d2c3-.../extractions\n```\n\n**Alternative \u2014 Webhooks:** Configure a delivery destination and binding\nto receive `document.extracted` events via POST callback. See the\nDelivery tag for setup details.\n\n**Job status state machine:**\n`pending` \u2192 `queued` \u2192 `processing` \u2192 `complete` | `failed`\n\nCancelled jobs transition directly to `failed` from `pending` or `processing`.\n\n## Operational Details\n\n**Uptime SLA:**\n- Free: best effort\n- Pro: 99.5%\n- Enterprise: 99.9% (custom SLA available)\n\n**Timeouts:** Synchronous extractions time out after 120 seconds. For\ndocuments that may take longer, use `async: true`. Async jobs have no\ntimeout \u2014 they run to completion or failure.\n\n**Payload limits:**\n- File upload (extract, ingest): 500 MB\n- JSON request bodies (schemas, jobs): 1 MB\n- PATCH corrections: 1 MB\n\n**Idempotency keys:** Pass an `Idempotency-Key` header on POST requests.\nKeys are valid for 24 hours. A duplicate request returns the cached\nresponse with `cached: true` in the body. Keys are scoped per API key.\n',
     contact: {
       name: "Talonic Support",
       email: "support@talonic.ai",
@@ -68,7 +68,7 @@ var openapi_default = {
     },
     {
       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"
+      description: 'Outbound delivery. Configure destinations (webhook, sftp, s3, azure_blob,\ngoogle_drive, onedrive, google_sheets), create bindings that join signal\nfilters to deliverable types + serializers, and inspect delivery history.\n\n## Webhook Delivery Contract\n\n**Payload envelope:**\n```json\n{\n  "event": {\n    "event_type": "document.extracted",\n    "event_id": "42",\n    "binding_id": "uuid",\n    "idempotency_key": "a1b2c3...32-char-hex",\n    "attempt": 1,\n    "delivered_at": "2026-04-25T14:30:00.000Z"\n  },\n  "payload": { "...serialized data..." }\n}\n```\n\n**Headers:** `X-Talonic-Event`, `X-Talonic-Delivery`, `X-Talonic-Signature`,\n`X-Talonic-Attempt`, `X-Talonic-Idempotency-Key`.\n\n**Signature verification (HMAC-SHA256):**\n```\nX-Talonic-Signature: t=1714060200000,v1=abc123...\nsigned = HMAC-SHA256(signing_secret, "${timestamp}.${body}")\n```\n\n**Event types:** `document.extracted`, `document.extraction_failed`,\n`run.dataspace.completed`, `run.dataspace.failed`,\n`result.dataspace.completed`, `result.approved`, `result.rejected`,\n`delivery.item.completed`, `delivery.item.failed` (17 total).\n\n**Retry policy:** Up to 7 attempts with exponential backoff:\n0s \u2192 30s \u2192 2m \u2192 8m \u2192 30m \u2192 2h \u2192 8h (~10.5h total).\nHTTP 429 and 5xx are retryable. HTTP 4xx (except 408) goes to DLQ immediately.\n\n**Dead-letter queue:** Failed deliveries land in the DLQ. Replay via\n`POST /v1/delivery/dlq/{id}/replay` which re-enqueues with attempt=1\nand the same idempotency key.\n'
     },
     {
       name: "Filter",
@@ -143,6 +143,61 @@ var openapi_default = {
       description: "Workspace context snapshot and tool discovery for the embedded AI agent."
     }
   ],
+  "x-tagGroups": [
+    {
+      name: "Getting Started",
+      tags: [
+        "Extract"
+      ]
+    },
+    {
+      name: "Core Resources",
+      tags: [
+        "Documents",
+        "Extractions",
+        "Schemas",
+        "Jobs"
+      ]
+    },
+    {
+      name: "Data Pipeline",
+      tags: [
+        "Sources",
+        "Batches",
+        "Routing",
+        "Delivery",
+        "Filter",
+        "Review"
+      ]
+    },
+    {
+      name: "Intelligence",
+      tags: [
+        "Matching",
+        "Cases",
+        "Linking",
+        "Fields",
+        "Reference Data",
+        "Dialects",
+        "Document Types",
+        "Schema Graph",
+        "N-Shot",
+        "Resolutions"
+      ]
+    },
+    {
+      name: "Platform",
+      tags: [
+        "Usage",
+        "Credits",
+        "Quality",
+        "Telemetry",
+        "Validation",
+        "Structuring",
+        "Agent"
+      ]
+    }
+  ],
   paths: {
     "/v1/extract": {
       post: {
@@ -1057,6 +1112,45 @@ var openapi_default = {
               "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"
+                  }
                 }
               }
             }
@@ -1592,6 +1686,34 @@ var openapi_default = {
               "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"
+                  }
                 }
               }
             }
@@ -1744,6 +1866,10 @@ var openapi_default = {
             "application/json": {
               schema: {
                 $ref: "#/components/schemas/SourceCreateRequest"
+              },
+              example: {
+                name: "Invoice Pipeline",
+                default_schema_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
               }
             }
           }
@@ -1769,6 +1895,24 @@ var openapi_default = {
                       }
                     }
                   ]
+                },
+                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"
+                  }
                 }
               }
             }
@@ -10543,8 +10687,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10557,8 +10706,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10571,8 +10725,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10585,8 +10744,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10599,8 +10763,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10613,8 +10782,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10627,9 +10801,13 @@ var openapi_default = {
               $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"
               }
@@ -10656,11 +10834,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10673,9 +10853,13 @@ var openapi_default = {
               $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"
             }
           }
         }
@@ -10685,29 +10869,50 @@ var openapi_default = {
       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: {
-            type: "object",
-            additionalProperties: {
-              type: "string"
-            },
-            description: "Related resource links."
+          path: {
+            type: "string",
+            description: "Request path that failed.",
+            example: "/v1/schemas"
           }
         }
       },

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 Lifecycle\n\nEnd-to-end async flow:\n\n**Step 1 — Submit extraction with `async: true`:**\n```\nPOST /v1/extract\nContent-Type: multipart/form-data\nAuthorization: Bearer tlnc_live_abc123\n\nfile=@contract.pdf\noptions={\"async\": true}\n```\nResponse `202 Accepted`:\n```json\n{\n  \"request_id\": \"req_x7y8z9a0\",\n  \"status\": \"processing\",\n  \"document\": { \"id\": \"f0e1d2c3-...\" },\n  \"poll_url\": \"/v1/documents/f0e1d2c3-...\"\n}\n```\n\n**Step 2 — Poll for completion:**\n```\nGET /v1/documents/f0e1d2c3-...\n```\nResponse `200` (when done): `\"status\": \"completed\"`\n\n**Step 3 — Retrieve results:**\n```\nGET /v1/documents/f0e1d2c3-.../extractions\n```\n\n**Alternative — Webhooks:** Configure a delivery destination and binding\nto receive `document.extracted` events via POST callback. See the\nDelivery tag for setup details.\n\n**Job status state machine:**\n`pending` → `queued` → `processing` → `complete` | `failed`\n\nCancelled jobs transition directly to `failed` from `pending` or `processing`.\n\n## Operational Details\n\n**Uptime SLA:**\n- Free: best effort\n- Pro: 99.5%\n- Enterprise: 99.9% (custom SLA available)\n\n**Timeouts:** Synchronous extractions time out after 120 seconds. For\ndocuments that may take longer, use `async: true`. Async jobs have no\ntimeout — they run to completion or failure.\n\n**Payload limits:**\n- File upload (extract, ingest): 500 MB\n- JSON request bodies (schemas, jobs): 1 MB\n- PATCH corrections: 1 MB\n\n**Idempotency keys:** Pass an `Idempotency-Key` header on POST requests.\nKeys are valid for 24 hours. A duplicate request returns the cached\nresponse with `cached: true` in the body. Keys are scoped per API key.\n",
     "contact": {
       "name": "Talonic Support",
       "email": "support@talonic.ai",
@@ -67,7 +67,7 @@
     },
     {
       "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"
+      "description": "Outbound delivery. Configure destinations (webhook, sftp, s3, azure_blob,\ngoogle_drive, onedrive, google_sheets), create bindings that join signal\nfilters to deliverable types + serializers, and inspect delivery history.\n\n## Webhook Delivery Contract\n\n**Payload envelope:**\n```json\n{\n  \"event\": {\n    \"event_type\": \"document.extracted\",\n    \"event_id\": \"42\",\n    \"binding_id\": \"uuid\",\n    \"idempotency_key\": \"a1b2c3...32-char-hex\",\n    \"attempt\": 1,\n    \"delivered_at\": \"2026-04-25T14:30:00.000Z\"\n  },\n  \"payload\": { \"...serialized data...\" }\n}\n```\n\n**Headers:** `X-Talonic-Event`, `X-Talonic-Delivery`, `X-Talonic-Signature`,\n`X-Talonic-Attempt`, `X-Talonic-Idempotency-Key`.\n\n**Signature verification (HMAC-SHA256):**\n```\nX-Talonic-Signature: t=1714060200000,v1=abc123...\nsigned = HMAC-SHA256(signing_secret, \"${timestamp}.${body}\")\n```\n\n**Event types:** `document.extracted`, `document.extraction_failed`,\n`run.dataspace.completed`, `run.dataspace.failed`,\n`result.dataspace.completed`, `result.approved`, `result.rejected`,\n`delivery.item.completed`, `delivery.item.failed` (17 total).\n\n**Retry policy:** Up to 7 attempts with exponential backoff:\n0s → 30s → 2m → 8m → 30m → 2h → 8h (~10.5h total).\nHTTP 429 and 5xx are retryable. HTTP 4xx (except 408) goes to DLQ immediately.\n\n**Dead-letter queue:** Failed deliveries land in the DLQ. Replay via\n`POST /v1/delivery/dlq/{id}/replay` which re-enqueues with attempt=1\nand the same idempotency key.\n"
     },
     {
       "name": "Filter",
@@ -142,6 +142,61 @@
       "description": "Workspace context snapshot and tool discovery for the embedded AI agent."
     }
   ],
+  "x-tagGroups": [
+    {
+      "name": "Getting Started",
+      "tags": [
+        "Extract"
+      ]
+    },
+    {
+      "name": "Core Resources",
+      "tags": [
+        "Documents",
+        "Extractions",
+        "Schemas",
+        "Jobs"
+      ]
+    },
+    {
+      "name": "Data Pipeline",
+      "tags": [
+        "Sources",
+        "Batches",
+        "Routing",
+        "Delivery",
+        "Filter",
+        "Review"
+      ]
+    },
+    {
+      "name": "Intelligence",
+      "tags": [
+        "Matching",
+        "Cases",
+        "Linking",
+        "Fields",
+        "Reference Data",
+        "Dialects",
+        "Document Types",
+        "Schema Graph",
+        "N-Shot",
+        "Resolutions"
+      ]
+    },
+    {
+      "name": "Platform",
+      "tags": [
+        "Usage",
+        "Credits",
+        "Quality",
+        "Telemetry",
+        "Validation",
+        "Structuring",
+        "Agent"
+      ]
+    }
+  ],
   "paths": {
     "/v1/extract": {
       "post": {
@@ -1052,6 +1107,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"
+                  }
                 }
               }
             }
@@ -1573,6 +1667,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"
+                  }
                 }
               }
             }
@@ -1725,6 +1847,10 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SourceCreateRequest"
+              },
+              "example": {
+                "name": "Invoice Pipeline",
+                "default_schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
               }
             }
           }
@@ -1750,6 +1876,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"
+                  }
                 }
               }
             }
@@ -10524,8 +10668,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 +10687,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 +10706,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 +10725,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 +10744,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 +10763,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 +10782,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 +10815,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 +10834,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 +10850,50 @@
       "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": {
-            "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Related resource links."
+          "path": {
+            "type": "string",
+            "description": "Request path that failed.",
+            "example": "/v1/schemas"
           }
         }
       },

package/package.json

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