Workflows API

Manage workflows programmatically. List, create, update, delete, and execute workflows through the REST API. Most endpoints require the BUILDER role; execution requires the OPERATOR role.

Role requirements

Workflow CRUD operations require the BUILDER role. Executing a workflow requires the OPERATOR role. Listing workflows is available to all authenticated team members.

List Workflows

GET

/api/workflows

List all workflows for the current team

Query Parameters

Parameter	Type	Required	Description
`teamId`	UUID	Yes	The team to list workflows for
`page`	integer	No	Page number (default: 0)
`size`	integer	No	Page size (default: 20)
`search`	string	No	Filter by workflow name

Response

200 OK

{
  "content": [
    {
      "id": "uuid",
      "name": "Order Processing",
      "description": "Handles incoming orders",
      "active": true,
      "createdAt": "2026-02-17T10:00:00.000Z",
      "updatedAt": "2026-02-17T12:00:00.000Z",
      "nodeCount": 8,
      "lastExecutionStatus": "SUCCESS"
    }
  ],
  "totalElements": 42,
  "totalPages": 3,
  "number": 0,
  "size": 20
}

Create Workflow

POST

/api/workflows

Create a new workflow (requires BUILDER role)

Request Body

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	No	Optional description
`teamId`	UUID	Yes	Team the workflow belongs to
`nodes`	array	No	Initial node definitions
`edges`	array	No	Initial edge definitions

Request

{
  "name": "Order Processing",
  "description": "Handles incoming orders from the API",
  "teamId": "uuid",
  "nodes": [],
  "edges": []
}

Response

201 Created

{
  "id": "uuid",
  "name": "Order Processing",
  "description": "Handles incoming orders from the API",
  "active": false,
  "teamId": "uuid",
  "createdAt": "2026-02-17T10:00:00.000Z",
  "updatedAt": "2026-02-17T10:00:00.000Z"
}

Update Workflow

PUT

/api/workflows/:id

Update an existing workflow (requires BUILDER role)

Request Body

Field	Type	Required	Description
`name`	string	No	Updated workflow name
`description`	string	No	Updated description
`active`	boolean	No	Activate or deactivate the workflow
`nodes`	array	No	Updated node definitions
`edges`	array	No	Updated edge definitions

Request

{
  "name": "Order Processing v2",
  "active": true,
  "nodes": [...],
  "edges": [...]
}

Response

Returns the updated workflow object with a 200 OK status.

Activating workflows

Setting active: true will register any scheduled triggers with the scheduler. Make sure the workflow has a valid trigger node before activating.

Delete Workflow

DELETE

/api/workflows/:id

Delete a workflow (requires BUILDER role)

Path Parameters

Parameter	Type	Description
`id`	UUID	The workflow ID to delete

Response

200 OK

{
  "message": "Workflow deleted successfully"
}

Irreversible

Deleting a workflow also removes all associated execution history. This action cannot be undone.

Execute Workflow

POST

/api/workflows/:id/execute

Trigger a workflow execution (requires OPERATOR role)

Request Body

Field	Type	Required	Description
`data`	object	No	Input data passed to the trigger node
`teamId`	UUID	Yes	Team context for the execution

Request

{
  "teamId": "uuid",
  "data": {
    "orderId": 42,
    "customer": "Acme Corp"
  }
}

Response

202 Accepted

{
  "executionId": "uuid",
  "status": "RUNNING",
  "startedAt": "2026-02-17T10:30:00.000Z"
}

Async execution

Workflow execution is asynchronous. The response returns immediately with the execution ID. Poll GET /api/executions/:id to check the execution status and results.

Error Codes

Status	Meaning
`400`	Invalid request body or missing required fields
`403`	Insufficient permissions (requires BUILDER or OPERATOR role)
`404`	Workflow not found
`409`	Workflow name already exists in the team

Authentication

Executions