Run document pipelines and agent workflows, then poll execution status

Pipelines

The pipeline endpoints let you run a document through a single document type's pipeline (classify → extract → validate) or run an agent across a set of documents. Executions can be synchronous (wait for result) or asynchronous (poll for status).

Execution Status Object

execution_idstring
UUID of the execution.
context_idstring
Document type ID (pipeline runs) or agent:<goal> (agent runs).
context_display_namestring
Human-readable display name of the context.
tenant_idstring
statusstring
running, completed, failed
stepsobject[]

Array of step results in execution order.

Step Result
toolstring
Tool name (e.g. "classify", "extract", "validate").
ordernumber
Step index.
statusstring
success or failed
outputobject
Tool output.
errorstring
Error message if failed.
duration_msnumber
Step duration in milliseconds.
resultobject
Final output after all steps complete.
input_filenamestring
Original filename of the input document.
input_mime_typestring
MIME type of the input document.
file_urlstring
Relative URL to download the input file: /v1/pipeline/executions/{id}/file
started_atstring
ISO 8601 timestamp.
completed_atstring
ISO 8601 timestamp.
total_msnumber
Total wall-clock duration in milliseconds.

Endpoints

Run Pipeline

POST /v1/pipeline/run

Requires scope: write. Runs a document through a single document type's pipeline.

Sync vs async: Pass sync: true (default) to wait for the result inline. Pass sync: false for queued async execution — use GET /v1/pipeline/executions/{id} to poll.

Request body:

context_idstringrequired

Document type ID to run the pipeline for (must exist in the system).

inputobjectrequired

Input payload. At minimum: { "data": "<base64>", "mime_type": "image/jpeg", "filename": "doc.jpg" }. Additional fields are passed through to each pipeline step.

tenant_idstring

Tenant context for model routing and rate limiting.

syncboolean

true to wait for result (default). false for async — returns immediately with execution_id and status: "running".

webhook_urlstring

Optional URL to POST the completed result to. Used with async mode.

Example request:

{
  "context_id": "pan_card",
  "tenant_id": "acme-corp",
  "input": {
    "data": "<base64-encoded-image>",
    "mime_type": "image/jpeg",
    "filename": "pan_front.jpg"
  },
  "sync": true
}

Example response (200):

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "steps": [
    { "tool": "classify", "order": 0, "status": "success", "output": { "document_type": "pan_card", "confidence": 0.98 }, "duration_ms": 320 },
    { "tool": "extract", "order": 1, "status": "success", "output": { "extracted": { "name": "John Doe", "pan_number": "ABCDE1234F" } }, "duration_ms": 850 },
    { "tool": "validate", "order": 2, "status": "success", "output": { "valid": true, "violations": [] }, "duration_ms": 12 }
  ],
  "result": {
    "document_type": "pan_card",
    "extracted": { "name": "John Doe", "pan_number": "ABCDE1234F" },
    "valid": true
  },
  "total_ms": 1182
}

Async response (200):

{
  "execution_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running"
}
📝

Composite document types (multi-step parallel pipelines) always run via direct execution regardless of the sync parameter.

Run Agent

POST /v1/agent/run

Requires scope: write. Runs a deployed agent across a set of documents. Performs classification, extraction, validation, and cross-matching across all documents. Supports archive uploads.

Request body:

goalstringrequired

Agent goal identifier. The agent must be deployed.

documentsobject[]

Array of document objects. Each: { "data": "<base64>", "mime_type": "image/jpeg", "filename": "..." }. Required unless archive is provided.

archiveobject

ZIP/tar archive containing multiple documents. { "data": "<base64>" }. Unpacked automatically; all supported image and PDF files are processed.

tenant_idstring
syncboolean

true to wait for result (default). false for async execution.

webhook_urlstring

Optional webhook URL for async result delivery.

Example request:

{
  "goal": "kyc_verification",
  "tenant_id": "acme-corp",
  "documents": [
    { "data": "<base64>", "mime_type": "image/jpeg", "filename": "pan_card.jpg" },
    { "data": "<base64>", "mime_type": "image/jpeg", "filename": "aadhaar_front.jpg" }
  ],
  "sync": true
}

Response (200):

execution_idstring
statusstring
completed, failed, or running (async)
phasesobject[]

Results per document type (one phase per doc type processed).

Phase Result
doc_typestring
Document type ID.
statusstring
extractedobject
Merged extraction output.
validboolean
violationsobject[]
resultobject
Final agent result including cross-match outcome.
📝

For large document payloads (over ~1.5 MB total base64), the agent run executes synchronously even in async mode.

Get Execution Status

GET /v1/pipeline/executions/{execution_id}

Requires scope: read. Returns the current state of an execution (pipeline or agent run).

execution_idstringrequired
UUID of the execution.

Response (200): Execution Status object.

Download Execution Input File

GET /v1/pipeline/executions/{execution_id}/file

Requires scope: read. Streams the original input document from storage.

execution_idstringrequired

Response headers: Content-Disposition: inline; filename="<filename>", Cache-Control: private, max-age=3600.

List Executions

GET /v1/pipeline/executions

Requires scope: read.

Query parameters:

tenant_idstring

Filter by tenant.

limitnumber

Default 50, max 200.

pipeline_onlyboolean

If true, excludes agent executions (those with context_id starting with agent:). Default false.

Response (200): Array of Execution Status objects.

PreviousDocument TypesNextDocuments