Skip to main content

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.

warning

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

ParameterDescriptionTypeRequired/ Optional
nameThe name of the workflow to be executed.stringRequired.
versionThe workflow version. If unspecified, the latest version will be used.integerRequired.

Query parameters

ParameterDescriptionTypeRequired/ Optional
requestIdA user-generated request ID, which can be used to track the API request.stringOptional.
waitUntilTaskRefThe reference name of the task to wait for before returning a response. If the workflow is incomplete, the response will return 206.stringOptional.
waitForSecondsThe duration in seconds to wait before returning a response. Default is 10.integerOptional.
consistencySpecifies how the request persists and is replicated. Supported values:
  • SYNCHRONOUS—Executes the workflow directly from memory without persisting the request. This option offers the lowest latency but is non-durable.
  • DURABLE—The request is stored in persistence before the workflow execution. This ensures reliable execution.
  • REGION_DURABLE—The request is replicated across regions before the workflow execution. This method provides the highest level of durability and fault tolerance but may introduce additional latency.
Default is DURABLE.
stringOptional.
returnStrategyIf the workflow includes a Yield task, this parameter defines the strategy for when the API returns a response. Supported values:
  • TARGET_WORKFLOW–Returns the state of the originally triggered workflow.
  • BLOCKING_WORKFLOW–Returns the state of the workflow that is currently blocking the execution, which may be a sub-workflow.
  • BLOCKING_TASK–Returns the execution status of the task that is currently blocking workflow execution.
  • BLOCKING_TASK_INPUT–Returns the input of the task that is currently blocking workflow execution. Useful for introspecting runtime behavior or debugging.
Default is TARGET_WORKFLOW.
stringOptional.

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"
}