Flow JSON reference

A flow is a JSON document: a slug, optional params and outputs, optional handlers, and a list of steps. Steps name elements of a library by their slugs; the runner finds them on the screen by their pixels. The hub, the attn CLI and the runner check flows against the same schema, which this page is generated from.

Add "$schema": "https://attention.run/schema/flow-v1.json" to a flow file and editors that read JSON Schema (VS Code among them) check it as you type.

{
  "$schema": "https://attention.run/schema/flow-v1.json",
  "flow": "acme/export-invoices",
  "name": "Export invoices",
  "library": "acme",
  "params": { "month": { "type": "string", "default": "2026-09" } },
  "outputs": { "exported": { "type": "number" } },
  "defaults": { "timeout": 10000 },
  "handlers": [
    {
      "id": "cookies",
      "when": { "visible": "global/cookie-accept" },
      "do": [{ "click": "global/cookie-accept" }],
      "max": 1
    }
  ],
  "steps": [
    { "call": "acme/sign-in" },
    { "click": "nav/invoices" },
    { "type": "{{params.month}}", "into": "invoices/month", "clear": true },
    { "scroll": { "dy": 400, "until": { "visible": "invoices/export" }, "max": 10 } },
    { "find": "invoices/row", "as": "rows", "all": true },
    { "set": { "exported": "{{vars.rows.count}}" } },
    { "if": { "var": "rows.count", "eq": 0 }, "then": [{ "pass": "nothing to export" }] },
    { "click": "invoices/export", "id": "export" },
    { "waitFor": { "visible": "toast/export-started" }, "timeout": 5000, "optional": true },
    { "assert": { "gone": "invoices/spinner" }, "timeout": 60000 }
  ]
}

The flow

Steps

Each step is an object with one action key (click, if, …) and that action’s fields, plus any of the fields every step takes.

Fields of every step

{ "click": "login/sign-in" }

{ "doubleClick": "invoice/number" }

{ "rightClick": "files/report" }

{ "hover": "nav/settings" }

{ "drag": { "from": "board/card", "to": "board/done-column" } }

{ "type": { "param": "user" }, "into": "login/username" }

{ "press": "Enter" }

{ "navigate": "https://example.com/login" }

{ "scroll": { "dy": 400, "until": { "visible": "invoices/export" }, "max": 10 } }

{ "waitFor": { "visible": "welcome/heading" }, "timeout": 5000 }

{ "waitStable": { "forMs": 500 } }

{ "wait": 1000 }

{ "assert": { "gone": "login/sign-in" }, "message": "still on the sign-in page" }

{ "find": { "element": "settings/toggle", "index": 0 }, "as": "toggle" }

{
  "read": {
    "text": { "element": "invoice/number-label", "rect": { "x": 90, "y": 0, "width": 160, "height": 20 } }
  },
  "as": "invoiceNo",
  "matches": "INV-(\\d+)"
}

{ "set": { "greeting": "Hello {{params.user}}", "first": "{{vars.rows.items.0}}" } }

{ "if": { "visible": "login/error" }, "then": [{ "fail": "Sign-in was refused" }] }

{
  "switch": [
    { "when": { "visible": "welcome/heading" }, "do": [{ "pass": "signed in" }] },
    { "when": { "visible": "verify/code" }, "do": [{ "call": "fixture/verify" }] }
  ]
}

{
  "repeat": { "until": { "gone": "list/spinner" }, "max": 20 },
  "do": [{ "scroll": { "dy": 300 } }]
}

{
  "forEach": { "in": "rows", "as": "row" },
  "do": [{ "click": { "element": "row/edit", "within": "row" } }]
}

{ "try": [{ "click": "dialog/close", "timeout": 2000 }], "catch": [{ "press": "Escape" }] }

{ "call": "fixture/sign-in", "params": { "user": "{{params.user}}" }, "as": "signin" }

{ "pass": "no invoices to export" }

{ "fail": "Sign-in was refused" }

Waiting and matching

Every step that acts on an element waits for it first, up to the step’s timeout. A wait after an action only looks at frames from after that action, so a dialog that was already on screen doesn’t end the wait for the next one.

An element that matches in more than one place fails with AMBIGUOUS, and the error lists the places: pick one with index, within or region, or cut a larger element.

Selectors

A selector names an element: its slug as a string, or an object with the slug and narrowing fields.

Targets

Actions take a target: where the pointer goes.

Conditions

waitFor, assert, if, switch, repeat, scroll.until and handlers take a condition. The value tests of var and param are eq, ne, gt, gte, lt, lte, matches, exists (at most one).

Placeholders

Strings in steps can name values with placeholders: {{params.user}} (a param), {{vars.row.cx}} (a var, with dotted paths into objects and lists such as {{vars.rows.items.0.state}}), and {{run.id}}, {{run.flow}}, {{run.version}}, {{run.target}}. Objects interpolate as JSON. There is no expression language: arithmetic and parsing belong in a script.

The validator checks that each placeholder names a declared param, a var some step sets, or a run field.

Params and outputs

Params are inputs: { "type": …, "default"?: …, "description"?: … }. Types are string, number, boolean, json (any JSON value). Text spells the other types, so --param count=3 fills a number param: "42" and "-1.5" are numbers, "true" and "false" booleans. A param without a default is required; a run with an unknown, missing or unconvertible param is refused.

Outputs are what a run returns: { "type"?: …, "default"?: …, "description"?: … } (no type: any JSON). An output is the var of the same name when the flow ends, so set, find, read and call … as write them. A run that passes must have every declared output, of its type; failed runs keep the ones that were set. At most 64 KB as JSON. Runs show them in attn run --wait, GET /runs/:id, webhooks and triggers ({{event.run.outputs.name}}).

Handlers

Handlers deal with what can appear at any time: { "id", "when", "do", "max"? }. Whenever when becomes true during the run, the next safe point (a wait, or between steps; never in the middle of an action) runs do, then the interrupted wait goes on. max is how many times it may run (default 3). A fail in a handler fails the run.

Results and errors

A run ends passed, failed (a step failed, or fail), error (the target or the setup broke) or cancelled. A failed step’s error has a code (TIMEOUT, AMBIGUOUS, NOT_FOUND, CAPABILITY, CONNECTOR, CANCELLED, ASSERTION, FAILED, INVALID), a message, the frame at the failure and the best candidate the matcher saw, such as the element at 0.71 against a threshold of 0.86.

Validation

Before a flow is saved (and before attn flows push sends it) it is checked: the schema, with an error per step and its path (steps[3].click); element slugs against the library (unknown ones are errors, proposed ones warnings); placeholders; params and outputs; calls (the flow exists, takes the params given, and no call leads back to the caller). Warnings: a wait, a type with no into before any click, steps after pass or fail.

The JSON Schema: https://attention.run/schema/flow-v1.json. How flows run: Concepts.