Workflows - Powabase

Workflows are DAG-based automation pipelines that execute a fixed sequence of blocks (LLM calls, code execution, conditions, agent runs). Unlike agents that decide what to do dynamically, workflows follow a predetermined graph. They can be executed directly, streamed, or triggered externally via webhooks.

Common Patterns

Create a workflow, define its graph with PUT /api/workflows/{id}/graph, then execute. For external triggers, deploy the workflow and arm it to get a webhook URL. Webhooks are single-use, so re-arm after each trigger. Use the streaming endpoint for real-time block execution updates.

CRUD

GET /api/workflows

List workflows.

limit

integer

Max results

offset

integer

Pagination offset

requests.get(f"{BASE_URL}/api/workflows", headers=headers)

await fetch(`${BASE_URL}/api/workflows`, { headers });

curl '{BASE_URL}/api/workflows' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/workflows

Create a workflow.

{ "name": "My Workflow" }

requests.post(f"{BASE_URL}/api/workflows", headers=headers, json={"name": "My Workflow"})

await fetch(`${BASE_URL}/api/workflows`, { method: "POST", headers, body: JSON.stringify({ name: "My Workflow" }) });

curl -X POST '{BASE_URL}/api/workflows' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "My Workflow"}'

GET /api/workflows/

Get workflow with blocks and edges.

string

required

Workflow ID

requests.get(f"{BASE_URL}/api/workflows/{wf_id}", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}`, { headers });

curl '{BASE_URL}/api/workflows/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/workflows/

Update workflow metadata.

string

required

Workflow ID

requests.patch(f"{BASE_URL}/api/workflows/{wf_id}", headers=headers, json={"name": "Renamed"})

await fetch(`${BASE_URL}/api/workflows/${wfId}`, { method: "PATCH", headers, body: JSON.stringify({ name: "Renamed" }) });

curl -X PATCH '{BASE_URL}/api/workflows/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "Renamed"}'

DELETE /api/workflows/

Delete a workflow.

string

required

Workflow ID

requests.delete(f"{BASE_URL}/api/workflows/{wf_id}", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/workflows/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Graph

PUT /api/workflows//graph

Save the complete graph: blocks and edges.

string

required

Workflow ID

{
  "blocks": [
    { "id": "start", "type": "starter", "config": {}, "position": {"x": 0, "y": 0} },
    { "id": "out", "type": "response", "config": {}, "position": {"x": 300, "y": 0} }
  ],
  "edges": [
    { "source": "start", "target": "out" }
  ]
}

Unknown block types are rejected with 400 Unknown block type. Canonical types: starter, webhook, agent, orchestration, code, condition, general_api, platform_api, response, split (plus back-compat aliases function → code, api_call → general_api).

requests.put(f"{BASE_URL}/api/workflows/{wf_id}/graph", headers=headers, json={"blocks": [...], "edges": [...]})

await fetch(`${BASE_URL}/api/workflows/${wfId}/graph`, { method: "PUT", headers, body: JSON.stringify({ blocks: [...], edges: [...] }) });

curl -X PUT '{BASE_URL}/api/workflows/{id}/graph' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"blocks": [], "edges": []}'

Deploy

POST /api/workflows//deploy

Deploy the workflow (enables webhook triggering).

string

required

Workflow ID

requests.post(f"{BASE_URL}/api/workflows/{wf_id}/deploy", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}/deploy`, { method: "POST", headers });

curl -X POST '{BASE_URL}/api/workflows/{id}/deploy' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/workflows//undeploy

Undeploy the workflow.

string

required

Workflow ID

requests.post(f"{BASE_URL}/api/workflows/{wf_id}/undeploy", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}/undeploy`, { method: "POST", headers });

curl -X POST '{BASE_URL}/api/workflows/{id}/undeploy' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/workflows//arm

Arm the workflow’s webhook for a single external trigger. Opens a 10-minute window during which the webhook accepts exactly one call; after it fires or expires, re-arm.

string

required

Workflow ID

The response is {"ok": true, "armed_until": "<iso8601>"}, not a webhook id/secret. The webhook_id and webhook_secret live on the webhook block’s config in the saved graph; fetch them with GET /api/workflows/{id} and read from the block whose type == "webhook".

response = requests.post(f"{BASE_URL}/api/workflows/{wf_id}/arm", headers=headers)
print(response.json())  # {"ok": true, "armed_until": "2026-01-01T00:00:00Z"}

const res = await fetch(`${BASE_URL}/api/workflows/${wfId}/arm`, { method: "POST", headers });
const { ok, armed_until } = await res.json();

curl -X POST '{BASE_URL}/api/workflows/{id}/arm' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Execution

POST /api/workflows//execute

Execute the workflow synchronously.

string

required

Workflow ID

variables

object

Map of input variable names → values. Defaults to {} when omitted.

variables is the canonical key. The route also accepts input as a legacy alias (data.get("variables", data.get("input", {}))); prefer variables in new code.

{ "variables": { "text": "..." } }

requests.post(f"{BASE_URL}/api/workflows/{wf_id}/execute", headers=headers, json={"variables": {"text": "..."}})

await fetch(`${BASE_URL}/api/workflows/${wfId}/execute`, { method: "POST", headers, body: JSON.stringify({ variables: { text: "..." } }) });

curl -X POST '{BASE_URL}/api/workflows/{id}/execute' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"variables": {"text": "..."}}'

POST /api/workflows//execute/stream

Execute with streaming SSE. Same body shape as /execute: pass variables (canonical) or input (legacy alias).

string

required

Workflow ID

variables

object

Map of input variable names → values. Defaults to {} when omitted.

requests.post(f"{BASE_URL}/api/workflows/{wf_id}/execute/stream", headers=headers, json={"variables": {"text": "..."}}, stream=True)

await fetch(`${BASE_URL}/api/workflows/${wfId}/execute/stream`, { method: "POST", headers, body: JSON.stringify({ variables: { text: "..." } }) });

curl -N -X POST '{BASE_URL}/api/workflows/{id}/execute/stream' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"variables": {"text": "..."}}'

GET /api/workflows//executions

List execution history.

string

required

Workflow ID

requests.get(f"{BASE_URL}/api/workflows/{wf_id}/executions", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}/executions`, { headers });

curl '{BASE_URL}/api/workflows/{id}/executions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/workflows//executions//logs

Get per-block execution logs.

string

required

Workflow ID

eid

string

required

Execution ID

requests.get(f"{BASE_URL}/api/workflows/{wf_id}/executions/{exec_id}/logs", headers=headers)

await fetch(`${BASE_URL}/api/workflows/${wfId}/executions/${execId}/logs`, { headers });

curl '{BASE_URL}/api/workflows/{id}/executions/{eid}/logs' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Error Responses

Workflow routes return one of two body shapes:

Plain {"error": "<message>"}: list/create/patch/delete and the deploy/undeploy/arm endpoints.
Structured {"error": "<message>", "error_code": "<UPPER_SNAKE_CODE>"} (via the shared error_response helper): GET /workflows/{id}, PUT /workflows/{id}/graph, and the synchronous /execute endpoint.

Streaming endpoints (/execute/stream) return HTTP 200 and emit errors as SSE data: {"type": "error", ...} events; only the timeout event includes error_code (EXECUTION_TIMEOUT).

Status	`error_code`	Description
400	—	Missing required field (e.g. `name`, no fields to update, no JSON body)
400	`VALIDATION_ERROR`	Graph save: each block needs `id`/`type`, each edge needs `source`/`target`, block types must be in the engine registry, and edges must reference blocks in the same graph
404	`WORKFLOW_NOT_FOUND`	No workflow exists with the given ID (`GET /workflows/{id}`, `PUT /graph`, `POST /execute`)
404	—	No workflow or execution exists with the given ID (other endpoints)
504	`EXECUTION_TIMEOUT`	Synchronous `/execute` exceeded its timeout
500	`EXECUTION_FAILED`	Synchronous `/execute` raised an error

​Common Patterns

​CRUD

​GET /api/workflows

​POST /api/workflows

​GET /api/workflows/

​PATCH /api/workflows/

​DELETE /api/workflows/

​Graph

​PUT /api/workflows//graph

​Deploy

​POST /api/workflows//deploy

​POST /api/workflows//undeploy

​POST /api/workflows//arm

​Execution

​POST /api/workflows//execute

​POST /api/workflows//execute/stream

​GET /api/workflows//executions

​GET /api/workflows//executions//logs

​Error Responses

Common Patterns

CRUD

GET /api/workflows

POST /api/workflows

GET /api/workflows/

PATCH /api/workflows/

DELETE /api/workflows/

Graph

PUT /api/workflows//graph

Deploy

POST /api/workflows//deploy

POST /api/workflows//undeploy

POST /api/workflows//arm

Execution

POST /api/workflows//execute

POST /api/workflows//execute/stream

GET /api/workflows//executions

GET /api/workflows//executions//logs

Error Responses