Skip to main content
POST
/
v1
/
workflows
/
runs
from retab import Retab
from pathlib import Path

client = Retab()

# Run with documents only
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start_document-block-1": Path("invoice.pdf"),
    }
)

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start_document-block-1": Path("invoice.pdf"),
    },
    json_inputs={
        "start-json-block-1": {"customer_id": "cust_123", "priority": "high"},
    }
)

print(f"Run started: {run.id}")
print(f"Lifecycle: {run.lifecycle.status}")
{
  "id": "run_abc123xyz",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "ver_abc123xyz"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "running" },
  "timing": {
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": null
  },
  "inputs": {
    "documents": {
      "start_document-block-1": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    },
    "json_data": {}
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

Create a workflow run. The canonical API route is flat: workflow_id belongs in the request body, not in the URL. The response returns immediately with lifecycle.status set to "running" or "pending" — use the Get Run endpoint to check for updates. Workflows can accept two types of inputs:
  • documents: File inputs for Document (start) blocks
  • json_inputs: JSON data for JSON Input (start_json) blocks
from retab import Retab
from pathlib import Path

client = Retab()

# Run with documents only
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start_document-block-1": Path("invoice.pdf"),
    }
)

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start_document-block-1": Path("invoice.pdf"),
    },
    json_inputs={
        "start-json-block-1": {"customer_id": "cust_123", "priority": "high"},
    }
)

print(f"Run started: {run.id}")
print(f"Lifecycle: {run.lifecycle.status}")
{
  "id": "run_abc123xyz",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "ver_abc123xyz"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "running" },
  "timing": {
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": null
  },
  "inputs": {
    "documents": {
      "start_document-block-1": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    },
    "json_data": {}
  }
}

Authorizations

Api-Key
string
header
required

Body

application/json

Create a new workflow run from a workflow id, an optional version selector, and optional inputs.

workflow_id
string
required

Workflow id for the fresh run.

documents
Documents · object

Mapping of start_document block IDs to their input documents.

json_inputs
Json Inputs · object

Mapping of start-json block IDs to their input JSON data.

version
string
default:production

Workflow version to run: 'production', 'draft', or a pinned version id like 'ver_...'. Only valid for fresh-run creation.

Examples:

"production"

"draft"

"ver_abc123def456"

Response

Successful Response

A single execution of a workflow.

id
string
required

Unique ID for this run

workflow_id
string
required

ID of the workflow that was run

workflow_version_id
string
required

Content-addressed workflow version used for this run.

trigger
TriggerInfo · object
required

What started this run

lifecycle
PendingRun · object
required

The run has been created but execution has not started.

timing
RunTiming · object
required

All timing information

inputs
RunInputs · object

Input payloads supplied at run creation time