Workflows API

Create, manage, and execute multi-step agent workflows

Workflows API

Create, manage, and execute multi-step agent workflows.

All workflow endpoints require session authentication. Workflows are scoped to the authenticated user — you can only access workflows that belong to your account.

List workflows

GET /api/workflows

Returns all workflows owned by the authenticated user, ordered by most recently updated. Each workflow includes its associated nodes.

Response

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Email Automation",
      "description": null,
      "enabled": true,
      "createdAt": "2026-03-29T10:00:00Z",
      "updatedAt": "2026-03-29T11:00:00Z",
      "nodes": [
        {
          "id": "node_1",
          "type": "trigger",
          "config": "{\"label\":\"Trigger 1\"}",
          "position": "{\"x\":40,\"y\":40}"
        }
      ]
    }
  ]
}

Field	Type	Description
workflows	array	List of workflow objects owned by the authenticated user
workflows[].id	string	Workflow identifier
workflows[].name	string	Workflow name
workflows[].description	string | null	Optional workflow description
workflows[].enabled	boolean	Whether the workflow is active
workflows[].createdAt	string	ISO 8601 creation timestamp
workflows[].updatedAt	string	ISO 8601 last update timestamp
workflows[].nodes	array	List of workflow nodes
workflows[].nodes[].id	string	Node identifier
workflows[].nodes[].type	string	Node type (trigger, action, condition, or output)
workflows[].nodes[].config	string	JSON-encoded node configuration including the node label
workflows[].nodes[].position	string	JSON-encoded {x, y} coordinates for the node in the visual builder

Errors

Code	Description
401	Unauthorized — returns { "workflows": [] } instead of an error object
500	Failed to load workflows

When the session is missing or invalid, this endpoint returns an empty workflows array with a 401 status instead of a standard error object.

Create workflow

POST /api/workflows

Creates a new workflow with optional initial nodes. The workflow is enabled by default.

Request body

Field	Type	Required	Description
name	string	Yes	Workflow name
description	string	No	Workflow description
nodes	array	No	Initial nodes to create with the workflow
nodes[].type	string	Yes	Node type. One of: trigger, action, condition, output
nodes[].config	object	No	Node configuration (for example, { "label": "My Node" }). Stored as a JSON string. Defaults to {}.
nodes[].position	object	No	Node position (for example, { "x": 40, "y": 40 }). Stored as a JSON string. Defaults to { "x": 0, "y": 0 }.

Response (201 Created)

{
  "workflow": {
    "id": "wf_abc123",
    "name": "Email Automation",
    "description": null,
    "enabled": true,
    "createdAt": "2026-03-29T10:00:00Z",
    "updatedAt": "2026-03-29T10:00:00Z",
    "nodes": []
  }
}

Errors

Code	Description
400	Name required
401	Unauthorized
500	Failed to create workflow

Get workflow

GET /api/workflows/:workflowId

Returns a single workflow with its nodes ordered by creation time. Requires ownership.

Path parameters

Parameter	Type	Description
workflowId	string	Workflow identifier

Response

{
  "workflow": {
    "id": "wf_abc123",
    "name": "Email Automation",
    "description": "Processes inbound emails",
    "enabled": true,
    "createdAt": "2026-03-29T10:00:00Z",
    "updatedAt": "2026-03-29T11:00:00Z",
    "nodes": [
      {
        "id": "node_1",
        "type": "trigger",
        "config": "{\"label\":\"Email Received\"}",
        "position": "{\"x\":40,\"y\":40}",
        "createdAt": "2026-03-29T10:00:00Z"
      }
    ]
  }
}

Errors

Code	Description
401	Unauthorized
404	Workflow not found or not owned by user
500	Internal server error

Update workflow

PUT /api/workflows/:workflowId

Updates a workflow’s metadata and optionally replaces all nodes. Requires ownership. When nodes is provided, all existing nodes are deleted and replaced with the new set.

Path parameters

Parameter	Type	Description
workflowId	string	Workflow identifier

Request body

Field	Type	Required	Description
name	string	No	Updated workflow name
description	string	No	Updated workflow description
enabled	boolean	No	Enable or disable the workflow
nodes	array	No	Complete replacement set of nodes. When provided, all existing nodes are deleted first.
nodes[].type	string	Yes	Node type. One of: trigger, action, condition, output
nodes[].config	object	No	Node configuration. Stored as a JSON string. Defaults to {}.
nodes[].position	object	No	Node position. Stored as a JSON string. Defaults to { "x": 0, "y": 0 }.

Providing the nodes field replaces all existing nodes. To update workflow metadata without affecting nodes, omit the nodes field entirely.

Response

{
  "workflow": {
    "id": "wf_abc123",
    "name": "Email Automation v2",
    "description": "Updated workflow",
    "enabled": true,
    "createdAt": "2026-03-29T10:00:00Z",
    "updatedAt": "2026-03-29T12:00:00Z",
    "nodes": [
      {
        "id": "node_new_1",
        "type": "trigger",
        "config": "{\"label\":\"Trigger 1\"}",
        "position": "{\"x\":40,\"y\":40}"
      },
      {
        "id": "node_new_2",
        "type": "action",
        "config": "{\"label\":\"Action 1\"}",
        "position": "{\"x\":240,\"y\":120}"
      }
    ]
  }
}

Errors

Code	Description
401	Unauthorized
404	Workflow not found or not owned by user
500	Internal server error

Delete workflow

DELETE /api/workflows/:workflowId

Permanently deletes a workflow and all its nodes. Requires ownership.

Path parameters

Parameter	Type	Description
workflowId	string	Workflow identifier

Response

{
  "deleted": true
}

Errors

Code	Description
401	Unauthorized
404	Workflow not found or not owned by user
500	Internal server error

Node types

Workflows support four node types:

Type	Description
trigger	Entry point that starts the workflow
action	Performs an operation such as an API call or message send
condition	Evaluates a condition and branches the flow
output	Produces a final result or side effect

Each node stores its configuration and visual position as JSON strings. The config object typically includes a label field used for display in the visual builder.