Execute Workflow Synchronously
Available since
v5.1.0 and later
Endpoint: POST /api/workflow/execute/{name}/{version}
Starts a workflow execution synchronously with the given consistency, which defines how reliably the request is stored and replicated before processing.
If the workflow includes a Yield task, the endpoint returns the response based on the returnStrategy
. This endpoint is ideal for real-time systems that require immediate feedback or workflow chaining.
Path parameters
Parameter | Description | Type | Required/ Optional |
---|---|---|---|
name | The name of the workflow to be executed. | string | Required. |
version | The workflow version. If unspecified, the latest version will be used. | integer | Required. |
Query parameters
Parameter | Description | Type | Required/ Optional |
---|---|---|---|
requestId | A user-generated request ID, which can be used to track the API request. | string | Optional. |
waitUntilTaskRef | The reference name of the task to wait for before returning a response. If the workflow is incomplete, the response will return 206. | string | Optional. |
waitForSeconds | The duration in seconds to wait before returning a response. Default is 10. | integer | Optional. |
consistency | Specifies how the request persists and is replicated. Supported values:
| string | Optional. |
returnStrategy | If the workflow includes a Yield task, this parameter defines the strategy for when the API returns a response. Supported values:
| string | Optional. |
Request body
Contains the workflow inputs. Format the request body as an object containing key-value pairs.
Example
{
"someKey": “someValue”,
"anotherKey": {}
}
Response
By default, the API returns the workflow’s current state upon synchronous execution. If a Yield task is present, the response is governed by the specified returnStrategy
.
Examples
Execute a workflow synchronously
Request
curl -X 'POST' \
'https://<YOUR-CLUSTER>/api/workflow/execute/understand_sync_async/1?waitForSeconds=5&consistency=DURABLE' \
-H 'accept: application/json' \
-H 'X-Authorization: <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"someKey":"someValue"}'
Response
{
"workflowId": "714b8006-5817-11f0-b9c7-fa37a82f8148",
"input": {},
"output": {},
"priority": 0,
"variables": {},
"tasks": [
{
"taskType": "HTTP",
"status": "SCHEDULED",
"inputData": {
"encode": true,
"headers": {},
"method": "GET",
"asyncComplete": false,
"service": "httpBinDemo",
"_createdBy": "john.doe@acme.com",
"body": {},
"uri": "http://httpbin:8081/api/hello/with-delay?name=test&delaySeconds=10",
"contentType": "application/json",
"accept": "application/json"
},
"referenceTaskName": "http_ref",
"retryCount": 0,
"seq": 1,
"pollCount": 0,
"taskDefName": "http",
"scheduledTime": 1751551815771,
"startTime": 0,
"endTime": 0,
"updateTime": 0,
"startDelayInSeconds": 0,
"retried": false,
"executed": false,
"callbackFromWorker": true,
"responseTimeoutSeconds": 0,
"workflowInstanceId": "714b8006-5817-11f0-b9c7-fa37a82f8148",
"workflowType": "understand_sync_async",
"taskId": "715a2607-5817-11f0-b9c7-fa37a82f8148",
"callbackAfterSeconds": 0,
"outputData": {},
"workflowTask": {
"name": "http",
"taskReferenceName": "http_ref",
"inputParameters": {
"uri": "http://httpbin:8081/api/hello/with-delay?name=test&delaySeconds=10",
"method": "GET",
"accept": "application/json",
"contentType": "application/json",
"encode": true,
"service": "httpBinDemo",
"body": {},
"headers": {},
"asyncComplete": false
},
"type": "HTTP",
"decisionCases": {},
"defaultCase": [],
"forkTasks": [],
"startDelay": 0,
"joinOn": [],
"optional": false,
"taskDefinition": {
"createTime": 0,
"updateTime": 0,
"retryCount": 3,
"timeoutSeconds": 0,
"inputKeys": [],
"outputKeys": [],
"timeoutPolicy": "TIME_OUT_WF",
"retryLogic": "FIXED",
"retryDelaySeconds": 60,
"responseTimeoutSeconds": 3600,
"inputTemplate": {},
"rateLimitPerFrequency": 0,
"rateLimitFrequencyInSeconds": 1,
"backoffScaleFactor": 1,
"totalTimeoutSeconds": 0,
"inputSchema": {
"createTime": 0,
"updateTime": 0,
"version": 1
},
"outputSchema": {
"createTime": 0,
"updateTime": 0,
"name": "sayHelloWithDelay",
"version": 1,
"type": "JSON"
},
"enforceSchema": false
},
"defaultExclusiveJoinTask": [],
"asyncComplete": false,
"loopOver": [],
"onStateChange": {},
"permissive": false
},
"rateLimitPerFrequency": 0,
"rateLimitFrequencyInSeconds": 0,
"workflowPriority": 0,
"iteration": 0,
"subworkflowChanged": false,
"firstStartTime": 0,
"queueWaitTime": 0,
"loopOverTask": false,
"taskDefinition": {
"createTime": 0,
"updateTime": 0,
"retryCount": 3,
"timeoutSeconds": 0,
"inputKeys": [],
"outputKeys": [],
"timeoutPolicy": "TIME_OUT_WF",
"retryLogic": "FIXED",
"retryDelaySeconds": 60,
"responseTimeoutSeconds": 3600,
"inputTemplate": {},
"rateLimitPerFrequency": 0,
"rateLimitFrequencyInSeconds": 1,
"backoffScaleFactor": 1,
"totalTimeoutSeconds": 0,
"inputSchema": {
"createTime": 0,
"updateTime": 0,
"version": 1
},
"outputSchema": {
"createTime": 0,
"updateTime": 0,
"name": "sayHelloWithDelay",
"version": 1,
"type": "JSON"
},
"enforceSchema": false
}
}
],
"createdBy": "john.doe@acme.com",
"createTime": 1751551815675,
"status": "RUNNING",
"updateTime": 0
}
Execute a workflow (which contains a Yield task) synchronously
Request
curl -X 'POST' \
'https://<YOUR-CLUSTER>/api/workflow/execute/complex_wf_signal_test_subworkflow_1/1?waitForSeconds=10&consistency=DURABLE&returnStrategy=BLOCKING_TASK' \
-H 'accept: application/json' \
-H 'X-Authorization: <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"someKey":"someValue"}'
Response
{
"responseType": "BLOCKING_TASK",
"targetWorkflowId": "c5c86ec9-5818-11f0-8395-5666a87fdc98",
"targetWorkflowStatus": "RUNNING",
"workflowId": "c5c86ec9-5818-11f0-8395-5666a87fdc98",
"input": {
"_createdBy": "john.doe@acme.com"
},
"output": {},
"taskType": "YIELD",
"taskId": "c5d4cadb-5818-11f0-8395-5666a87fdc98",
"referenceTaskName": "simple_ref_1",
"retryCount": 0,
"taskDefName": "yield",
"workflowType": "complex_wf_signal_test_subworkflow_1",
"priority": 0,
"createTime": 0,
"updateTime": 0,
"status": "IN_PROGRESS"
}