| type | docs |
|---|---|
| title | Workflow API reference |
| linkTitle | Workflow API |
| weight | 1600 |
Dapr provides users with the ability to interact with workflows through its built-in workflow engine, which is implemented using Dapr Actors.
To interact with the workflow engine, see [how to author]{{% ref howto-author-workflow.md %}} and [manage workflows]({{% ref howto-manage-workflow.md %}}).
Below is the reference for the Dapr Workflow API. This API is deprecated and will eventually be removed.
Start a workflow instance with the given name and optionally, an instance ID.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<workflowName>/start[?instanceID=<instanceID>]
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
{{% alert title="Important" color="warning" %}} Workflow instance IDs cannot be reused. If a workflow with the given instance ID already exists (in any state), the request will be rejected. To reuse an instance ID, first purge the workflow using the [purge API]({{% ref "workflow_api.md#purge-workflow-request" %}}). See [workflow identity]({{% ref "workflow-features-concepts.md#workflow-identity" %}}) for more details. {{% /alert %}}
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
workflowName |
Identify the workflow type |
instanceID |
(Optional) Unique value created for each run of a specific workflow |
Any request content will be passed to the workflow as input. The Dapr API passes the content as-is without attempting to interpret it.
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
409 |
A workflow with the given instance ID already exists |
500 |
Request formatted correctly, error in dapr code |
The API call will provide a response similar to this:
{
"instanceID": "12345678"
}Terminate a running workflow instance with the given name and instance ID.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/terminate
{{% alert title="Note" color="primary" %}} Terminating a workflow terminates all of the child workflows created by the workflow instance.
Terminating a workflow has no effect on any in-flight activity executions that were started by the terminated instance.
{{% /alert %}}
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
500 |
Request formatted correctly, error in dapr code |
This API does not return any content.
For workflow components that support subscribing to external events, such as the Dapr Workflow engine, you can use the following "raise event" API to deliver a named event to a specific workflow instance.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceID>/raiseEvent/<eventName>
{{% alert title="Note" color="primary" %}} The exact mechanism for subscribing to an event depends on the workflow component that you're using. Dapr Workflow has one way of subscribing to external events but other workflow components might have different ways.
{{% /alert %}}
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
eventName |
The name of the event to raise |
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
500 |
Request formatted correctly, error in dapr code or underlying component |
None.
Pause a running workflow instance.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/pause
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
500 |
Error in Dapr code or underlying component |
None.
Resume a paused workflow instance.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/resume
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
500 |
Error in Dapr code |
None.
Purge the workflow state from your state store with the workflow's instance ID.
POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/purge
{{% alert title="Note" color="primary" %}}
Only COMPLETED, FAILED, or TERMINATED workflows can be purged.
{{% /alert %}}
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
| Code | Description |
|---|---|
202 |
Accepted |
400 |
Request was malformed |
500 |
Error in Dapr code |
None.
Get information about a given workflow instance.
GET http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>
| Parameter | Description |
|---|---|
workflowComponentName |
Use dapr for Dapr Workflows |
instanceId |
Unique value created for each run of a specific workflow |
| Code | Description |
|---|---|
200 |
OK |
400 |
Request was malformed |
500 |
Error in Dapr code |
The API call will provide a JSON response similar to this:
{
"createdAt": "2023-01-12T21:31:13Z",
"instanceID": "12345678",
"lastUpdatedAt": "2023-01-12T21:31:13Z",
"properties": {
"property1": "value1",
"property2": "value2",
},
"runtimeStatus": "RUNNING",
}| Parameter | Description |
|---|---|
runtimeStatus |
The status of the workflow instance. Values include: "RUNNING", "COMPLETED", "CONTINUED_AS_NEW", "FAILED", "CANCELED", "TERMINATED", "PENDING", "SUSPENDED" |