Overview

Workflow executions are running instances of workflow definitions. Each execution represents a single process that progresses through states based on transitions you trigger.

Execution Lifecycle

1

Create Execution

Start a new workflow instance by posting to the executions endpoint:

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "definitionId": "leave-request"
}'
View in Swagger UI
2

Execution Starts

The execution begins in the "start" state defined in your workflow definition. The system validates input data against the workflow's input schema.

3

Trigger Transitions

Use the available transitions to progress the workflow through states. Check the availableTransitions array in the execution response.

4

Completion

When the workflow reaches a final state (no transitions), the status becomes completed.

Getting Execution Status

Retrieve the current status and details of an execution: 

curl -X 'GET' \
  'https://app.yworkflow.com/api/executions/{executionId}' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012'

The response includes:

{
  "id": "74659490-b855-42dc-9b0f-54f8040d8778",
  "definitionId": "leave-request",
  "version": "v1",
  "status": "started",
  "inputs": {},
  "currentStates": ["draft"],
  "availableTransitions": ["submit"]
}
id
Unique execution identifier
currentStates
Array of active state IDs (supports fork/join with multiple states)
availableTransitions
Array of valid transition IDs you can trigger from current state(s)
status
Current execution status: created, started, processing, stopped, killed, or completed

Triggering Transitions

Progress the workflow by triggering a transition: 

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions/{executionId}/transitions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "transitionId": "submit"
}'
View in Swagger UI

💡 Parallel Execution: After triggering a transition that leads to a fork, the workflow splits into parallel states. The currentStates array will contain multiple state IDs.

🔐 Role-Based Access Control: The availableTransitions array only shows transitions you're authorized to perform based on your API key's role and the state's owners.

Fork and Join Behavior

Fork Behavior

When a workflow reaches a fork state, it creates multiple active states simultaneously. Each branch executes independently.

Example: After triggering "submit" in the leave-request workflow, currentStates will contain both ["hr_check", "manager_check"].

Join Behavior

Join states merge parallel branches back together:

  • wait_all: All branches must reach the join state before proceeding
  • wait_any: Any branch reaching the join state allows proceeding

The join state waits until the condition is met, then automatically transitions to the target state.

Error Handling

400 Bad Request

Transition logic error (guard failed, action not available)

404 Not Found

Execution not found

409 Conflict

Workflow locked/busy or completed (state conflict). Retry after a brief delay.

422 Unprocessable Entity

Input validation failed. Check that your input matches the transition's input schema.

API Endpoints

GET /api/executions

List all workflow executions with pagination (cursor-based).

POST /api/executions

Start a new workflow instance. Body includes definitionId, optional version, and input data.

GET /api/executions/{id}

Get execution status and details, including current states and available transitions.

POST /api/executions/{id}/transitions

Trigger a transition to move the workflow from current state to next state.

Previous: Workflow Definitions Next: Webhooks