Flows

Flows are per-table automations (triggers). Over the Public API you can list, read, create, update, delete, enable/disable, validate, and inspect the run logs of a table's flows.

All flow endpoints require an account API key (il_live_) with access to the workspace, and the key acts as a workspace admin — flows are an admin-level surface. Personal (il_user_) keys cannot author flows. Read-only keys can read (list, get, validate, get_logs, brick_context) but not create, update, delete, or set_active.

Authoring modes

A flow's logic lives in its code field, which holds either:

• Builder JSON — the visual builder's brick tree, {"version":1,"bricks":[…]}. This is the recommended machine-authored format: it round-trips into the visual editor so a human can keep editing it.
• PHPScript — raw code (the "code mode" escape hatch).

The format is auto-detected: a code value that JSON-decodes to an object with a bricks key is treated as builder mode, otherwise as PHPScript.

Triggers

Set on trigger at create time (and changeable via update):

web / wpg flows are assigned a public token (webhook_id) automatically.

Recommended workflow

1. Fetch the table schema (GET /api/table/<id>/get) for field ids.
2. Optionally call brick_context / brick_context_preview to discover the tokens, tables, and fields valid at a brick position.
3. Author the brick tree and validate it (flows/validate) — no persistence, returns the compiled PHPScript or a validation error.
4. Create the flow (starts inactive).
5. Enable it with set_active.

List flows for a table

GET /api/table/<table_id>/flows/list

Returns id / name / trigger / active / err_flag for every flow on the table (not the code). Use get to read a single flow's logic.

Get a single flow

GET /api/table/<table_id>/flow/<flow_id>/get

Returns the full flow including code (builder JSON or PHPScript), trigger, settings, active, and err_flag. This is the read-before-edit endpoint.

Validate (dry run)

POST /api/table/<table_id>/flows/validate

Body {"code": "<builder JSON or PHPScript>"}. Does not persist. Builder JSON is validated against the table schema (unknown field ids / tokens are rejected) and compiled; PHPScript is linted.

// builder mode
{"ok": true, "mode": "builder", "compiled": "…compiled PHPScript…"}
// code mode
{"ok": true, "mode": "code"}

On failure the call returns a non-2xx with the validation / lint message.

Create a flow

POST /api/table/<table_id>/flows/create

{
  "trigger": "crt",
  "data": {
    "name": "Stamp created date",
    "code": "{\"version\":1,\"bricks\":[…]}",
    "active": false
  }
}

trigger is required. data is optional; supported keys: name, code, active, settings. New flows default to inactive — enable with set_active after you've confirmed the logic. Returns the created flow.

When the code is builder JSON, it is validated against the table schema on save; un-compilable JSON is rejected with the validation error rather than persisted.

Update a flow

POST /api/table/<table_id>/flow/<flow_id>/update

{
  "data": {
    "id": 456,
    "name": "Renamed",
    "code": "{\"version\":1,\"bricks\":[…]}",
    "trigger": "upd",
    "settings": {}
  }
}

data.id and data.name are required. id, table_id, and account_id are ignored if sent (the path is authoritative). Changing trigger to web/wpg auto-generates a public token if the flow doesn't have one. Builder code is schema-validated on save. Returns the updated flow.

Enable / disable

POST /api/table/<table_id>/flow/<flow_id>/set_active

Body: a truthy value enables, empty/false disables (e.g. {"active": 1}). Blocked for read-only keys.

Delete a flow

POST /api/table/<table_id>/flow/<flow_id>/delete

Run logs

POST /api/table/<table_id>/flow/<flow_id>/get_logs

Body {"offset": 0} (optional). Returns a page of run-log rows for debugging a flow's executions.

Brick context (authoring discovery)

POST /api/table/<table_id>/flow/<flow_id>/brick_context   # existing flow
POST /api/table/<table_id>/flows/brick_context_preview     # unsaved / new flow

Body: {"bricks": {"bricks":[…]}, "brickId": "<target brick id>"} (preview also takes trigger, and both accept additional_workspaces). Returns the variables, {{tokens}}, tables, select options, multi-value fields, and workspace users valid at that brick's position — use these to author valid bricks before saving.

Builder JSON

Each brick is {"id","type","config"}, with container bricks (if, if_expr, foreach) nesting under children (and else_children for if / if_expr). Minimal example — on an upd flow, set a checkbox when a number crosses a threshold:

{
  "version": 1,
  "bricks": [
    {
      "id": "b1",
      "type": "if",
      "config": {"left": "{{record.number}}", "operator": ">", "right": "250"},
      "children": [
        {
          "id": "b2",
          "type": "update_record",
          "config": {
            "source": "object|record|<db_table>",
            "fields": [{"key": "single-check", "value": "bar"}]
          }
        }
      ]
    }
  ]
}

Notes:

• config.fields (create/update) is an array of {key, value} objects — key is a field id, value is a token string.
• record_source_select values are pipe-delimited: object|record|<db_table> for the trigger record, object|<varName>|<db_table> for an object variable.
• Date / datetime / time fields are stored in UTC — stamp them with {{now.datetime_utc}} / {{now.date_utc}} / {{now.time_utc}}, not the local {{now.datetime}}.
• Available brick types include set_var, html_var, web_page, foreach, if, if_expr, query_records, get_records_from_view, get_record, get_related, create_record, update_record, delete_record, add_comment, send_email, generate_pdf, http_request, api_request, ai_prompt, assign_task, execute_flow, stop, continue, log, comment.

Always validate a brick tree against the target table before saving — the validator resolves field ids and tokens against the table schema and returns a precise error for anything it can't compile.

Errors