@talonic/docs 0.21.2 → 0.21.4

package/dist/seo.js

@@ -166,6 +166,10 @@ var openapi_default = {
       name: "Pipelines",
       description: "Run a configured Spec end to end (the One Engine) over a set of documents, poll progress, and produce a data product."
     },
+    {
+      name: "Run",
+      description: "One-call ingest + Spec-pipeline run. `POST /v1/run` accepts files and/or file URLs directly (no separate ingest step), starts the named Spec's compiled pipeline, and returns a poll target \u2014 unlike `POST /v1/pipelines`, which requires documents to already exist. Poll `GET /v1/run/{id}` or register a webhook (`POST /v1/webhooks`, events `run.completed` / `run.failed`) to be notified on completion.\n"
+    },
     {
       name: "Webhooks",
       description: "Outbound HMAC-signed event webhooks \u2014 configure endpoints and read the event catalog, delivery format, signature scheme, and retry policy."
@@ -17139,8 +17143,7 @@ var openapi_default = {
             description: "Created pipeline run with links to progress + data-product."
           },
           "400": {
-            description: "The Spec has no composed rail",
-            "or the body failed validation.": null
+            description: "The Spec has no composed rail, or the body failed validation."
           }
         }
       }
@@ -17339,6 +17342,213 @@ var openapi_default = {
         }
       }
     },
+    "/v1/run": {
+      post: {
+        tags: [
+          "Run"
+        ],
+        summary: "Ingest documents and run a Spec's pipeline in one call",
+        description: 'Accepts one or more files, one or more `file_urls`, or a mix of both \u2014 at least one input is required. Ingests every input (metering each ingest leg), waits for OCR to finish, then compiles the named Spec\'s saved rail into a pipeline and starts it \u2014 the same compile step `POST /v1/pipelines` uses, minus the separate "upload documents first" step. Always returns 202; poll `GET /v1/run/{id}` or listen for the `run.completed` / `run.failed` webhook (`POST /v1/webhooks`). Requires write scope. Unlike `POST /v1/process`, this endpoint does not dedup \u2014 every call starts a fresh run.\n',
+        operationId: "createRun",
+        security: [
+          {
+            BearerAuth: []
+          }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "multipart/form-data": {
+              schema: {
+                type: "object",
+                required: [
+                  "spec_id"
+                ],
+                properties: {
+                  spec_id: {
+                    type: "string",
+                    format: "uuid",
+                    description: "The Spec (user_schema) whose saved rail runs."
+                  },
+                  files: {
+                    type: "array",
+                    items: {
+                      type: "string",
+                      format: "binary"
+                    },
+                    description: "Zero or more document files (max 20 per call, 500 MB each). At least one of files/file_urls is required."
+                  },
+                  file_urls: {
+                    type: "array",
+                    items: {
+                      type: "string",
+                      format: "uri"
+                    },
+                    description: "Zero or more remote document URLs (SSRF-guarded downstream)."
+                  },
+                  name: {
+                    type: "string",
+                    maxLength: 200,
+                    description: "Optional display name for the run."
+                  },
+                  metadata: {
+                    type: "string",
+                    description: "Optional JSON string, persisted on the run request and returned by GET /v1/run/{id}."
+                  }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          "202": {
+            description: "Ingest + run accepted.",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    run_id: {
+                      type: "string",
+                      format: "uuid"
+                    },
+                    spec_id: {
+                      type: "string",
+                      format: "uuid"
+                    },
+                    status: {
+                      type: "string",
+                      enum: [
+                        "processing"
+                      ]
+                    },
+                    input_count: {
+                      type: "integer",
+                      description: "Total files + file_urls accepted."
+                    },
+                    poll_url: {
+                      type: "string",
+                      example: "/v1/run/3d44a4dc-e3e4-4bca-b079-a9c85bf75026"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            description: "Missing spec_id, no input provided (both files and file_urls empty), or metadata is not valid JSON."
+          },
+          "402": {
+            description: "Insufficient credits for an ingest leg."
+          },
+          "429": {
+            $ref: "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
+    "/v1/run/{id}": {
+      get: {
+        tags: [
+          "Run"
+        ],
+        summary: "Poll a /v1/run request",
+        description: "Row status, folded with the compiled pipeline's live progress once one exists (`pipeline_id` set). `status` is `processing` (ingest/OCR wait still running, no pipeline yet), `running` (pipeline active), `completed`, or `failed`. Requires read scope.\n",
+        operationId: "pollRunRequest",
+        security: [
+          {
+            BearerAuth: []
+          }
+        ],
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string",
+              format: "uuid"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "Run request status.",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    run_id: {
+                      type: "string",
+                      format: "uuid"
+                    },
+                    spec_id: {
+                      type: "string",
+                      format: "uuid"
+                    },
+                    status: {
+                      type: "string",
+                      enum: [
+                        "processing",
+                        "running",
+                        "completed",
+                        "failed"
+                      ]
+                    },
+                    pipeline_id: {
+                      type: "string",
+                      format: "uuid",
+                      nullable: true
+                    },
+                    input_count: {
+                      type: "integer"
+                    },
+                    error_message: {
+                      type: "string",
+                      nullable: true
+                    },
+                    metadata: {
+                      type: "object",
+                      nullable: true,
+                      additionalProperties: true,
+                      description: "The opaque JSON supplied on POST /v1/run, echoed back here."
+                    },
+                    created_at: {
+                      type: "string",
+                      format: "date-time"
+                    },
+                    updated_at: {
+                      type: "string",
+                      format: "date-time"
+                    },
+                    progress: {
+                      type: "object",
+                      nullable: true,
+                      description: "Present once the pipeline has started.",
+                      properties: {
+                        total_documents: {
+                          type: "integer"
+                        },
+                        completed_documents: {
+                          type: "integer"
+                        },
+                        error_documents: {
+                          type: "integer"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            description: "Run request not found."
+          }
+        }
+      }
+    },
     "/v1/webhooks": {
       get: {
         tags: [
@@ -17391,7 +17601,7 @@ var openapi_default = {
                     items: {
                       type: "string"
                     },
-                    description: "Event types to subscribe to (default: extraction.complete, extraction.failed)."
+                    description: "Event types to subscribe to (default: extraction.complete, extraction.failed). Includes run.completed / run.failed \u2014 fired on POST /v1/run pipeline completion (see GET /v1/webhooks/events for the full, current catalog)."
                   },
                   source_connection_id: {
                     type: "string",
@@ -17633,6 +17843,7 @@ var openapi_default = {
           "Webhooks"
         ],
         summary: "List supported webhook event types",
+        description: 'Live catalog served from code (not a static enum) \u2014 includes run.completed ("A /v1/run pipeline finished; structured output is available, review-held fields null") and run.failed ("A /v1/run pipeline failed \u2014 all documents errored during ingest or extraction") alongside the document/extraction/job/delivery/process event families.\n',
         operationId: "listWebhookEvents",
         security: [
           {
@@ -20367,7 +20578,7 @@ var openapi_default = {
             type: "string",
             format: "uuid",
             example: "f0e1d2c3-b4a5-9687-8765-432109876543",
-            description: "ID of the created document (absent if duplicate)."
+            description: "ID of the created document. When status is `duplicate`, this is the id of the linked-duplicate row created for this upload (see `existing_document_id` for the canonical document)."
           },
           filename: {
             type: "string",
@@ -20399,7 +20610,7 @@ var openapi_default = {
             ],
             format: "uuid",
             example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-            description: "Present when status is `duplicate`."
+            description: "Present when status is `duplicate` \u2014 the canonical document this upload deduplicated to (the linked duplicate reads its extracted data from it). The `document_id` field carries the id of the linked-duplicate row created for this upload."
           },
           links: {
             type: "object",

package/openapi.json

@@ -165,6 +165,10 @@
       "name": "Pipelines",
       "description": "Run a configured Spec end to end (the One Engine) over a set of documents, poll progress, and produce a data product."
     },
+    {
+      "name": "Run",
+      "description": "One-call ingest + Spec-pipeline run. `POST /v1/run` accepts files and/or file URLs directly (no separate ingest step), starts the named Spec's compiled pipeline, and returns a poll target — unlike `POST /v1/pipelines`, which requires documents to already exist. Poll `GET /v1/run/{id}` or register a webhook (`POST /v1/webhooks`, events `run.completed` / `run.failed`) to be notified on completion.\n"
+    },
     {
       "name": "Webhooks",
       "description": "Outbound HMAC-signed event webhooks — configure endpoints and read the event catalog, delivery format, signature scheme, and retry policy."
@@ -17119,8 +17123,7 @@
             "description": "Created pipeline run with links to progress + data-product."
           },
           "400": {
-            "description": "The Spec has no composed rail",
-            "or the body failed validation.": null
+            "description": "The Spec has no composed rail, or the body failed validation."
           }
         }
       }
@@ -17319,6 +17322,213 @@
         }
       }
     },
+    "/v1/run": {
+      "post": {
+        "tags": [
+          "Run"
+        ],
+        "summary": "Ingest documents and run a Spec's pipeline in one call",
+        "description": "Accepts one or more files, one or more `file_urls`, or a mix of both — at least one input is required. Ingests every input (metering each ingest leg), waits for OCR to finish, then compiles the named Spec's saved rail into a pipeline and starts it — the same compile step `POST /v1/pipelines` uses, minus the separate \"upload documents first\" step. Always returns 202; poll `GET /v1/run/{id}` or listen for the `run.completed` / `run.failed` webhook (`POST /v1/webhooks`). Requires write scope. Unlike `POST /v1/process`, this endpoint does not dedup — every call starts a fresh run.\n",
+        "operationId": "createRun",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "spec_id"
+                ],
+                "properties": {
+                  "spec_id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "The Spec (user_schema) whose saved rail runs."
+                  },
+                  "files": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "binary"
+                    },
+                    "description": "Zero or more document files (max 20 per call, 500 MB each). At least one of files/file_urls is required."
+                  },
+                  "file_urls": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uri"
+                    },
+                    "description": "Zero or more remote document URLs (SSRF-guarded downstream)."
+                  },
+                  "name": {
+                    "type": "string",
+                    "maxLength": 200,
+                    "description": "Optional display name for the run."
+                  },
+                  "metadata": {
+                    "type": "string",
+                    "description": "Optional JSON string, persisted on the run request and returned by GET /v1/run/{id}."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Ingest + run accepted.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "run_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "spec_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "processing"
+                      ]
+                    },
+                    "input_count": {
+                      "type": "integer",
+                      "description": "Total files + file_urls accepted."
+                    },
+                    "poll_url": {
+                      "type": "string",
+                      "example": "/v1/run/3d44a4dc-e3e4-4bca-b079-a9c85bf75026"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Missing spec_id, no input provided (both files and file_urls empty), or metadata is not valid JSON."
+          },
+          "402": {
+            "description": "Insufficient credits for an ingest leg."
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
+    "/v1/run/{id}": {
+      "get": {
+        "tags": [
+          "Run"
+        ],
+        "summary": "Poll a /v1/run request",
+        "description": "Row status, folded with the compiled pipeline's live progress once one exists (`pipeline_id` set). `status` is `processing` (ingest/OCR wait still running, no pipeline yet), `running` (pipeline active), `completed`, or `failed`. Requires read scope.\n",
+        "operationId": "pollRunRequest",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Run request status.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "run_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "spec_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "processing",
+                        "running",
+                        "completed",
+                        "failed"
+                      ]
+                    },
+                    "pipeline_id": {
+                      "type": "string",
+                      "format": "uuid",
+                      "nullable": true
+                    },
+                    "input_count": {
+                      "type": "integer"
+                    },
+                    "error_message": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "metadata": {
+                      "type": "object",
+                      "nullable": true,
+                      "additionalProperties": true,
+                      "description": "The opaque JSON supplied on POST /v1/run, echoed back here."
+                    },
+                    "created_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "updated_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "progress": {
+                      "type": "object",
+                      "nullable": true,
+                      "description": "Present once the pipeline has started.",
+                      "properties": {
+                        "total_documents": {
+                          "type": "integer"
+                        },
+                        "completed_documents": {
+                          "type": "integer"
+                        },
+                        "error_documents": {
+                          "type": "integer"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Run request not found."
+          }
+        }
+      }
+    },
     "/v1/webhooks": {
       "get": {
         "tags": [
@@ -17371,7 +17581,7 @@
                     "items": {
                       "type": "string"
                     },
-                    "description": "Event types to subscribe to (default: extraction.complete, extraction.failed)."
+                    "description": "Event types to subscribe to (default: extraction.complete, extraction.failed). Includes run.completed / run.failed — fired on POST /v1/run pipeline completion (see GET /v1/webhooks/events for the full, current catalog)."
                   },
                   "source_connection_id": {
                     "type": "string",
@@ -17613,6 +17823,7 @@
           "Webhooks"
         ],
         "summary": "List supported webhook event types",
+        "description": "Live catalog served from code (not a static enum) — includes run.completed (\"A /v1/run pipeline finished; structured output is available, review-held fields null\") and run.failed (\"A /v1/run pipeline failed — all documents errored during ingest or extraction\") alongside the document/extraction/job/delivery/process event families.\n",
         "operationId": "listWebhookEvents",
         "security": [
           {
@@ -20347,7 +20558,7 @@
             "type": "string",
             "format": "uuid",
             "example": "f0e1d2c3-b4a5-9687-8765-432109876543",
-            "description": "ID of the created document (absent if duplicate)."
+            "description": "ID of the created document. When status is `duplicate`, this is the id of the linked-duplicate row created for this upload (see `existing_document_id` for the canonical document)."
           },
           "filename": {
             "type": "string",
@@ -20379,7 +20590,7 @@
             ],
             "format": "uuid",
             "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-            "description": "Present when status is `duplicate`."
+            "description": "Present when status is `duplicate` — the canonical document this upload deduplicated to (the linked duplicate reads its extracted data from it). The `document_id` field carries the id of the linked-duplicate row created for this upload."
           },
           "links": {
             "type": "object",

package/package.json

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