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 plus nodes, edges and context. A webhook trigger's token and secret are never included.
  • POST …/versions/{version}/restore saves that version's nodes, edges and context as a new version through the normal save (full validation) and returns the flow. The name, enabled and 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.