Flows API
List, create and edit flows, start a manual run, and read run history and step detail.
Flows are visual workflows: a trigger followed by conditions and actions. This API lists, creates and edits flows, starts a manual run, and reads run history, which is the way to wire AxisIQ into a deployment pipeline or check that scheduled flows are healthy.
Endpoints
| Method | Path | Permission | What it does |
|---|---|---|---|
GET |
/orgs/{orgId}/flows |
flows:read |
List flows |
POST |
/orgs/{orgId}/flows |
flows:create |
Create a flow (starts disabled) |
GET |
/orgs/{orgId}/flows/{flowId} |
flows:read |
Get a flow |
PUT |
/orgs/{orgId}/flows/{flowId} |
flows:update |
Replace a flow's definition |
DELETE |
/orgs/{orgId}/flows/{flowId} |
flows:delete |
Delete a flow |
POST |
/orgs/{orgId}/flows/{flowId}/run |
flows:run |
Start a manual run |
POST |
/orgs/{orgId}/flows/{flowId}/test |
flows:run |
Test run on sample data (nothing performed or stored) |
GET |
/orgs/{orgId}/flows/{flowId}/versions |
flows:read |
Saved versions, newest first |
GET |
/orgs/{orgId}/flows/{flowId}/versions/{version} |
flows:read |
One version with its graph |
POST |
/orgs/{orgId}/flows/{flowId}/versions/{version}/restore |
flows:update |
Restore a version as a new version |
GET |
/orgs/{orgId}/flows/{flowId}/runs |
flows:read |
Recent runs of one flow |
GET |
/orgs/{orgId}/flows/{flowId}/runs/{runId} |
flows:read |
One run with every step |
GET |
/orgs/{orgId}/flows/runs |
flows:read |
Runs across all flows |
GET |
/orgs/{orgId}/flows/overview |
flows:read |
Counts and trends for the Flows home |
POST |
/orgs/{orgId}/flows/generate |
flows:create |
Draft a flow from a description (not saved) |
Important: A flow runs with the permissions of whoever last changed its definition (nodes, connections, trigger or variables). That is a person or a service account. Enabling, renaming or moving blocks does not change it. A flow can never do something its last editor could not do, and a key that can edit flows can therefore only authorise actions the key itself holds.
The flow object
{
"id": "0190f0cc-…",
"name": "Alert on large invoices",
"description": "",
"enabled": true,
"trigger_kind": "record_event",
"trigger_type": "invoices",
"trigger_event": "created",
"next_run_at": null,
"last_run_at": "2026-10-04T09:30:02Z",
"nodes": [
{ "id": "t", "type": "trigger.record_event", "config": { "object_type": "invoices", "event": "created" }, "position": { "x": 0, "y": 0 } },
{ "id": "c", "type": "logic.condition", "config": { "match": "all", "clauses": [ … ] }, "position": { "x": 240, "y": 0 } }
],
"edges": [ { "id": "e1", "source": "t", "source_handle": "out", "target": "c" } ],
"context": { "threshold": "100000" },
"created_at": "2026-10-01T08:00:00Z",
"updated_at": "2026-10-04T09:00:00Z"
}
trigger_kind is record_event, schedule, manual, calendar, hr or webhook. The trigger_*, cron_expr and next_run_at fields are derived from the trigger block; you do not send them.
Blocks (nodes[].type)
Every trigger block also takes alert_on_failure (owner, the default, or off) and alert_members (up to 20 member ids): who is notified when a run fails.
A flow has exactly one trigger block and no loops back (it is a directed acyclic graph). source_handle on an edge says which output it leaves from.
| Type | Output handles | config |
|---|---|---|
trigger.record_event |
out |
object_type, event (created, updated or deleted) |
trigger.schedule |
out |
cron (a cron expression, evaluated in UTC) |
trigger.manual |
out |
none. Run it through the run route |
trigger.calendar_event |
out |
calendar_key (blank for any calendar), event (created, updated, cancelled or starting), minutes_before (for starting) |
trigger.webhook |
out |
signature_header, encoding (hex or base64), secret (write-only; reads back as secret_set), clear_secret, regenerate (true mints a new address on save). The server sets token; see Flow webhooks |
trigger.hr_event |
out |
event (leave_requested, leave_approved, leave_rejected, employee_joined or employee_exited) |
logic.approval |
approved, rejected |
approver (a member id), title, details. The run pauses until the approver decides |
logic.delay |
out |
minutes (1 to 43,200, which is 30 days) |
action.delete_record |
out |
object_type, record_id. Moves the record to the trash |
action.enqueue |
out |
queue_key, stage (blank = first stage), record_id, key (an open item with the same key is left alone) |
action.post_relay |
out |
channel_id, text |
action.notify |
out |
members (up to 20 member ids), title, body |
action.ask_axis |
out |
prompt. The answer is output.reply |
logic.condition |
true, false |
match (all or any), clauses |
logic.filter |
out |
list, match, clauses |
logic.reduce |
out |
list, op (sum, avg, min, max, count, join), field |
logic.for_each |
loop, done |
list |
action.create_record |
out |
object_type, values (field key to text) |
action.update_record |
out |
object_type, record_id, values |
action.run_function |
out |
function_id, input (key to text) |
action.http_request |
out |
method (GET, POST, PUT, PATCH, DELETE), url, headers, body |
action.send_message |
out |
connection_id, template_id, to, record_type, record_id, to_field, subject, body_text, body_html, vars |
action.create_event |
out |
calendar_key, title, description, location, start, end, duration_minutes, all_day, attendees, record_type, record_id |
Text values in config can contain {{…}} references to the trigger and to earlier blocks, for example {{trigger.record.number}} (a field of the record that fired the flow), {{trigger.record_id}}, {{trigger.input.name}} for a manual run, or {{context.threshold}} for the flow's context variables. The exact shapes are easiest to learn by building a flow in the editor and reading it back with GET /flows/{flowId}.
Outgoing HTTP calls from a flow only reach public internet addresses over http or https, with a 10 second timeout and a 1 MB response limit. A non-2xx answer from the other side is data, not a failure.
POST /orgs/{orgId}/flows
Create a flow. New flows start disabled, so you can build the graph step by step. Permission: flows:create.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | Yes | |
description |
string | No | |
enabled |
boolean | No | A flow can only be enabled when it is complete and valid |
nodes |
array | No | See above |
edges |
array | No | |
context |
object | No | Named text variables the blocks can reference |
Response 201 with the flow object. Errors: 400 VALIDATION_ERROR with a message naming the problem (unknown block type, no trigger, more than one trigger, a loop, a bad connection handle).
PUT /orgs/{orgId}/flows/{flowId}
Same body as create. It replaces the definition. Permission: flows:update. Response 200 with the flow object.
DELETE /orgs/{orgId}/flows/{flowId}
Returns 204 No Content.
POST /orgs/{orgId}/flows/{flowId}/run
Start a manual run. Permission: flows:run.
| Field | Type | Required | Notes |
|---|---|---|---|
input |
any JSON | No | Available to blocks as trigger.input |
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/flows/$FLOW/run \
-H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
-d '{"input": {"invoice": "INV-1001"}}'
{ "data": { "queued": true } }
The run happens in the background, so 202 means accepted, not finished. Poll the runs list for the result. A manual run executes even when the flow is disabled, which makes it a safe way to test. Runs are delivered at least once, so make actions safe to repeat.
Errors: 404 NOT_FOUND (no such flow), 403 FORBIDDEN.
The response status is 202.
POST /orgs/{orgId}/flows/{flowId}/test
Walks a graph on sample data without performing anything and returns what each block did or would do. The graph comes from the body — send the flow's current nodes/edges/context to test the saved version, or unsaved changes to test those. The flow id must exist. The test runs with the caller's permissions; nothing is sent, written, queued or stored as a run.
{ "nodes": [ … ], "edges": [ … ], "context": {}, "record_id": "0190f0cc-…", "input": { "status": "paid" } }
record_id— record-event trigger: the record to use. Omitted ⇒ the newest record of the trigger's type the caller can read.input— manual trigger: the run input. Webhook trigger: the request body. Record-event trigger: an object of field values laid over the record.
Response 200:
{
"trigger": { "kind": "record_event", "record": { "status": "paid", "phone": "" } },
"steps": [
{ "node_id": "c", "node_type": "logic.condition", "status": "ok", "output": { "result": "true" } },
{ "node_id": "m", "node_type": "action.send_message", "status": "simulated",
"output": { "simulated": true, "inputs": { "to": null, "body_text": "Thanks!" }, "warnings": ["to: {{trigger.record.phone}} came out empty"] } }
],
"notes": ["Using the newest record you can see."],
"stopped": false,
"actions": 1,
"duration_ms": 3
}
Logic blocks run for real (status ok/failed). Every action, approval and wait is simulated: inputs holds its configuration with every reference resolved, warnings lists references that resolved to nothing, and the rest of output is a stand-in result so later blocks can follow. An approval continues down its approved handle. A structurally invalid graph is 400 VALIDATION_ERROR.
Versions
Every save that changes nodes, edges, the trigger or context stores an immutable version; renames, the enabled switch and node positions do not. The newest 50 are kept. The flow object carries its current version, and each run carries the version it executed (absent on runs from before versions existed).
GET …/versions→[{ "version": 3, "name": "…", "created_by": "…", "created_by_name": "Alex Morgan", "created_at": "…" }], newest first, no graphs.GET …/versions/{version}→ the same plusnodes,edgesandcontext. A webhook trigger's token and secret are never included.POST …/versions/{version}/restoresaves that version'snodes,edgesandcontextas a new version through the normal save (full validation) and returns the flow. The name,enabledand the current webhook address stay. Like any definition change, the flow then runs as the caller.
An unknown version is 404 NOT_FOUND.
GET /orgs/{orgId}/flows/{flowId}/runs
Recent runs of one flow, newest first. Returns an array of run objects (up to 50).
GET /orgs/{orgId}/flows/runs
Runs across every flow, newest first. Cursor paging.
| Parameter | Notes |
|---|---|
status |
ok or failed |
flow |
A flow id |
from |
RFC 3339 time or YYYY-MM-DD: only runs at or after this |
limit |
Page size |
cursor |
The next_cursor of the previous page |
{
"data": {
"runs": [
{
"id": "0190f0dd-…",
"flow_id": "0190f0cc-…",
"flow_name": "Alert on large invoices",
"status": "failed",
"error": "update_record: record not found",
"trigger": { "kind": "record_event", "event": "created", "object_type": "invoices", "record_id": "0190f0aa-…" },
"started_at": "2026-10-04T09:30:02Z",
"finished_at": "2026-10-04T09:30:02Z"
}
],
"next_cursor": "0190f0dc-…"
}
}
next_cursor is null on the last page.
GET /orgs/{orgId}/flows/{flowId}/runs/{runId}
One run including every step:
{
"data": {
"id": "0190f0dd-…",
"flow_id": "0190f0cc-…",
"status": "ok",
"started_at": "2026-10-04T09:30:02Z",
"finished_at": "2026-10-04T09:30:03Z",
"steps": [
{ "node_id": "t", "node_type": "trigger.record_event", "status": "ok", "duration_ms": 0, "started_at": "2026-10-04T09:30:02Z" },
{ "node_id": "a1", "node_type": "action.create_record", "status": "ok", "output": { "id": "0190f0de-…" }, "duration_ms": 41, "started_at": "2026-10-04T09:30:02Z" }
]
}
}
A run's status is ok, failed or running. A step's is ok or failed, with error on a failed step.
GET /orgs/{orgId}/flows/overview
Counts for a dashboard: total, enabled, by_trigger, runs_24h and runs_7d (each {ok, failed}), a daily series, the failing and busiest flows, and upcoming scheduled runs.
POST /orgs/{orgId}/flows/generate
Body {"prompt": "…"}. Returns a proposed name, nodes, edges and context that you can review and save with a normal create. Nothing is saved. Answers 503 AGENT_DISABLED when AI drafting is unavailable.