Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
run
from retab import Retab
from pathlib import Path

client = Retab()

workflow = client.workflows.get_entities("wf_abc123xyz")
document_start_id = workflow.start_blocks[0].id
json_start_id = workflow.start_json_blocks[0].id

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

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        document_start_id: Path("invoice.pdf"),
    },
    json_inputs={
        json_start_id: {"customer_id": "cust_123", "priority": "high"},
    }
)

print(f"Run started: {run.id}")
print(f"Lifecycle: {run.lifecycle.kind}")
{
  "id": "run_abc123xyz",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "snapshot_id": "snap_abc123",
    "name_at_run_time": "Invoice Processing"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "kind": "running" },
  "timing": {
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": null,
    "human_waiting_started_at": null,
    "accumulated_human_waiting_ms": 0,
    "duration_ms": null,
    "active_duration_ms": null
  },
  "inputs": {
    "documents": {
      "start-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.

Run a workflow with the provided inputs. This endpoint creates a workflow run and starts execution in the background. The response returns immediately with lifecycle.kind 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
If you do not know the input block IDs yet, call client.workflows.get_entities(workflow_id) first and read .start_blocks / .start_json_blocks.
from retab import Retab
from pathlib import Path

client = Retab()

workflow = client.workflows.get_entities("wf_abc123xyz")
document_start_id = workflow.start_blocks[0].id
json_start_id = workflow.start_json_blocks[0].id

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

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        document_start_id: Path("invoice.pdf"),
    },
    json_inputs={
        json_start_id: {"customer_id": "cust_123", "priority": "high"},
    }
)

print(f"Run started: {run.id}")
print(f"Lifecycle: {run.lifecycle.kind}")
{
  "id": "run_abc123xyz",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "snapshot_id": "snap_abc123",
    "name_at_run_time": "Invoice Processing"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "kind": "running" },
  "timing": {
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": null,
    "human_waiting_started_at": null,
    "accumulated_human_waiting_ms": 0,
    "duration_ms": null,
    "active_duration_ms": null
  },
  "inputs": {
    "documents": {
      "start-block-1": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    },
    "json_data": {}
  }
}

Authorizations

Api-Key
string
header
required

Path Parameters

workflow_id
string
required

Body

application/json

Request to run a workflow with input documents and/or JSON.

Documents are provided as a dict mapping start block IDs to document inputs. JSON inputs are provided as a dict mapping start_json block IDs to JSON data.

Example: { "documents": { "start-block-1": { "filename": "invoice.pdf", "mime_type": "application/pdf", "content": "base64_encoded_content..." } }, "json_inputs": { "start-json-block-1": { "customer_name": "John Doe", "invoice_number": "INV-001" } }, }

documents
Documents · object

Mapping of start 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_...'

Examples:

"production"

"draft"

"ver_abc123def456"

Response

Successful Response

Public workflow run response without tenant isolation fields.

id
string
required

Unique ID for this run

workflow
WorkflowSnapshotRef · object
required

Workflow + snapshot reference

trigger
ManualTrigger · object
required

Manual run started by a user from the dashboard.

lifecycle
PendingRun · object

The run has been created but execution has not started.

timing
RunTiming · object

All timing information

inputs
RunInputs · object

Input payloads supplied at run creation time