Execute Workflow Synchronously
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.
The functionality described in this document is not available by default. To get access, please contact Orkes support or your Orkes account representative.
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"
}