conductor-oss--conductor/docs/documentation/api/startworkflow.md

description

description
Start Conductor workflow executions — asynchronous, synchronous, and dynamic workflow execution via REST API with curl examples.

Start Workflow API

Start a Workflow (Asynchronous)

POST /api/workflow

Starts a new workflow execution asynchronously. Returns the workflow ID immediately.

Request Body

Field	Description	Required
name	Workflow name (must be registered)	Yes
version	Workflow version	No (defaults to latest)
input	JSON object with input parameters for the workflow	No
correlationId	Unique ID to correlate multiple workflow executions	No
taskToDomain	Task-to-domain mapping. See Task Domains.	No
workflowDef	Inline Workflow Definition for dynamic workflows. See Dynamic Workflows.	No
externalInputPayloadStoragePath	Path to external payload storage. See External Payload Storage.	No
priority	Priority level (0–99) for tasks within this workflow	No

Example

curl -X POST 'http://localhost:8080/api/workflow' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "myWorkflow",
    "version": 1,
    "correlationId": "order-123",
    "priority": 1,
    "input": {
      "customerId": "CUST-456",
      "amount": 99.99
    },
    "taskToDomain": {
      "*": "mydomain"
    }
  }'

Response 200 OK — returns the workflow ID as plain text:

3a5b8c2d-1234-5678-9abc-def012345678

Start with Path Parameters

POST /api/workflow/{name}

Alternative way to start a workflow — specify the name in the path and pass input as the request body.

Parameter	Type	Description	Required
name	Path	Workflow name	Yes
version	Query	Workflow version	No
correlationId	Query	Correlation ID	No
priority	Query	Priority 0–99 (default: 0)	No

curl -X POST 'http://localhost:8080/api/workflow/myWorkflow?version=1&correlationId=order-123' \
  -H 'Content-Type: application/json' \
  -d '{"customerId": "CUST-456", "amount": 99.99}'

Response 200 OK — returns the workflow ID as plain text.

---

Execute a Workflow (Synchronous)

POST /api/workflow/execute/{name}/{version}

Starts a workflow and waits for completion (or a specified condition) before returning the result. This eliminates the need to poll for workflow status.

Parameter	Type	Description	Required
name	Path	Workflow name	Yes
version	Path	Workflow version (use 0 for latest)	Yes
requestId	Query	Idempotency key	No (auto-generated)
waitUntilTaskRef	Query	Comma-separated task reference names to wait for	No
waitForSeconds	Query	Maximum wait time in seconds	No (default: 10)
consistency	Query	DURABLE or EVENTUAL	No (default: DURABLE)
returnStrategy	Query	Controls which workflow state is returned	No (default: TARGET_WORKFLOW)

Request body: a StartWorkflowRequest object (same format as the async start).

Example

curl -X POST 'http://localhost:8080/api/workflow/execute/my_workflow/1?waitForSeconds=30' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my_workflow",
    "version": 1,
    "input": {
      "url": "https://api.example.com/data"
    }
  }'

Response 200 OK — returns the workflow execution result:

{
  "workflowId": "3a5b8c2d-1234-5678-9abc-def012345678",
  "requestId": "req-uuid",
  "status": "COMPLETED",
  "output": {
    "response": {...}
  },
  "tasks": [...]
}

Wait Behavior

• If waitUntilTaskRef is specified, the API returns when any listed task reaches a terminal state (or a WAIT task is encountered)
• If the workflow completes before the timeout, the result is returned immediately
• If the timeout is reached, the current workflow state is returned — the workflow continues running in the background
• Sub-workflow WAIT tasks are detected recursively

---

Dynamic Workflows

Start a one-time workflow without pre-registering its definition. Provide the full workflow definition inline via the workflowDef field.

curl -X POST 'http://localhost:8080/api/workflow' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my_adhoc_workflow",
    "workflowDef": {
      "ownerApp": "my_app",
      "ownerEmail": "owner@example.com",
      "name": "my_adhoc_workflow",
      "version": 1,
      "tasks": [
        {
          "name": "fetch_data",
          "type": "HTTP",
          "taskReferenceName": "fetch_data",
          "inputParameters": {
            "uri": "${workflow.input.uri}",
            "method": "GET"
          },
          "taskDefinition": {
            "name": "fetch_data",
            "retryCount": 0,
            "timeoutSeconds": 3600,
            "timeoutPolicy": "TIME_OUT_WF",
            "responseTimeoutSeconds": 3000
          }
        }
      ]
    },
    "input": {
      "uri": "https://api.example.com/data"
    }
  }'

Response 200 OK — returns the workflow ID as plain text.

!!! note If a taskDefinition is already registered via the Metadata API, it does not need to be included inline in the dynamic workflow definition.