Actions & workflow control

Actions are the steps an interface runs when called. Each action does one thing — fetch data or transform it — and actions can be ordered, retried, and run conditionally on each other's results.

An action's data comes from an input: selector (request data or a previous action's output), or from a fetch: http, database, command, email, or a lookup to fan out over an array. Then validate with assert, reshape with post_transforms, and order with run_when_succeeded / run_when_failed / depends_on.

actions:
  - name: FetchUser
    http:
      url: https://api.example.com/users/a|params::id|
  - name: Notify
    run_when_succeeded: [FetchUser]
    http:
      url: https://hooks.example.com/notify
      body: { email: a|FetchUser::email| }

Reference a previous action's output with a|ActionName::field| — see Interpolation. All action fields follow.

Action

Field	Type	Description
`timeout`	any	Maximum execution time for this action in milliseconds. Example ↓
`input`	string (nullable)	Specify the input source for the action. Common sources: - `a\|body\|` - HTTP request body - `a\|params\|` - URL parameters - `a\|action_name::field\|` - Output from a previous action Example ↓
`input_fallbacks`	Array<string> (nullable)	Alternative input sources to try if the primary input is not available. Example ↓
`conditional_input`	ConditionalInput (nullable)	Define conditional input based on runtime conditions. Uses Simple (list of input strings) or Complex (with tests). Example ↓
`pre_log`	Array<LogMessage> (nullable)	Log messages before action execution. Example ↓
`post_log`	Array<LogMessage> (nullable)	Log messages after successful action completion. Example ↓
`error_log`	Array<LogMessage> (nullable)	Log messages when action fails. Example ↓
`success_log`	Array<LogMessage> (nullable)	Log messages when action succeeds. Example ↓
`retry_log`	Array<LogMessage> (nullable)	Log messages when action retry is attempted. Example ↓
`retry`	Retry (nullable)	Configure automatic retry behavior. Example ↓
`lookup`	string (nullable)	Name of a lookup configuration to use for pre-fetching data. Example ↓
`item_timeout`	any	Per-item execution timeout for lookup iterations. Controls how long each individual item in the lookup array is allowed to run. Use `timeout` to cap the total loop duration. Example ↓
`lookup_concurrency`	number (nullable)	Maximum number of lookup items to execute concurrently. Defaults to 10. Capped at 50 in managed run modes. Example ↓
`lookup_partition`	boolean (nullable)	Separate per-item successes from failures in the lookup output. When true, the action returns `{ "succeeded": [...item data...], "failed": [{ item, http_code?, error?, data? }]… Example ↓
`lookup_inherit_jq`	Map<string, string> (nullable)	JQ transformations to apply to lookup results. Example ↓
`lookup_inherit`	Map<string, string> (nullable)	Fields to inherit from lookup results. Example ↓
`actions`	Array<Action> (nullable)	Nested actions for lookup. Example ↓
`json_output`	any	Capture specific JSON values from output. Example ↓
`command`	CommandRun (nullable)	Execute a system command. Example ↓
`output_stdout`	boolean (nullable)	Include command stdout in output. Example ↓
`http`	HttpRequest (nullable)	HTTP request configuration. Example ↓
`database`	string (nullable)	Database name for SQL operations. Example ↓
`google`	Google (nullable)	Google API integration. Example ↓
`aws`	Aws (nullable)	AWS service integration. Example ↓
`state`	StateAction (nullable)	Persistent state operation (durable key/value): polling cursors, dedupe sets, idempotency keys, counters. Backed by a pluggable backend (in-memory for local single-node,… Example ↓
`delay`	any	Pause for a fixed duration before continuing — pacing / throttling between steps. Accepts a duration string (`"2s"`, `"500ms"`, `"1m"`) or a number of milliseconds. Bounded by… Example ↓
`email`	Email (nullable)	Email sending action. Example ↓
`emit_metric`	EmitMetric (nullable)	Emit a Prometheus metric as part of this action step. Requires `expose_metrics: true` on the parent config. Example ↓
`ws_publish`	WsPublish (nullable)	Publish a payload to realtime WebSocket channels (server push / fan-out).
`mqtt_publish`	MqttPublish (nullable)	Publish a payload to MQTT topics (pipeline → topic, cross-node fan-out).
`action`	string (nullable)	Action identifier for referencing outputs. Example ↓
`depends_on`	RunCondition (nullable)	Run this action when specified actions complete. Can be a list of action names or a RunCondition config. Example ↓
`run_when_succeeded`	RunCondition (nullable)	Run this action when specified actions succeed. Example ↓
`run_when_failed`	RunCondition (nullable)	Run this action when specified actions fail. Example ↓
`run_on_assertion`	Assert (nullable)	Run this action based on assertion results. Example ↓
`params`	Array<any> (nullable)	Parameters for SQL queries. Example ↓
`post_transforms`	Array<Transform> (nullable)	Transformations to apply to action output. Example ↓
`name`	string (nullable)	Action identifier/name. Example ↓
`description`	string (nullable)	Description of the action. Example ↓
`query`	string (nullable)	SQL query for database actions. Example ↓
`multi`	boolean (nullable)	Run this action's `query` as a multi-statement batch (Postgres only). The native driver prepares every query, and a prepared statement can hold only one command — so a `query`… Example ↓
`url`	string (nullable)	URL for HTTP actions. Example ↓
`conn_string`	string (nullable)	Database connection string override. Example ↓
`output`	string (nullable)	Output destination handler. Example ↓
`assert`	Assert (nullable)	Validation and response configuration. Example ↓
`document_operation`	DocumentOperation (nullable)	Document database operations. Example ↓
`hide_action`	boolean (nullable)	Hide entire action data. Example ↓
`hide_data_on_success`	boolean (nullable)	Hide action data on success. Example ↓
`hide_data_on_error`	boolean (nullable)	Hide action data on error. Example ↓
`hide_data_on_empty`	boolean (nullable)	Hide action data when empty. Example ↓
`hide_errors`	boolean (nullable)	Hide error details. Example ↓
`hide_metrics`	boolean (nullable)	Disable metrics collection. Example ↓
`response_on_success`	ActionResponse (nullable)	Custom response on success. Example ↓
`response_on_error`	ActionResponse (nullable)	Custom response on error. Example ↓

Field examples

timeout

Maximum execution time for this action in milliseconds.

Example

timeout: 5000    # 5 seconds

input

Specify the input source for the action. Common sources:

a|body| - HTTP request body
a|params| - URL parameters
a|action_name::field| - Output from a previous action

Example

input: a|body|

Example

input: a|LoginBody::email|

input_fallbacks

Alternative input sources to try if the primary input is not available.

Example

input_fallbacks:
  - a|header::Authorization|
  - a|params::token|

conditional_input

Define conditional input based on runtime conditions. Uses Simple (list of input strings) or Complex (with tests).

Example - Simple

conditional_input:
  - a|body::premium|      # Try this first
  - a|body::standard|     # Fallback

Example - Complex

conditional_input:
  - input: a|body::type|
    tests:
      - is_equal_to: "premium"

pre_log

Log messages before action execution.

Example

pre_log:
  - msg: "Starting validation"
    level: info

post_log

Log messages after successful action completion.

Example

post_log:
  - msg: "Validation succeeded"
    level: info

error_log

Log messages when action fails.

Example

error_log:
  - msg: "Validation failed"
    level: error

success_log

Log messages when action succeeds.

Example

success_log:
  - msg: "Email sent"
    level: info

retry_log

Log messages when action retry is attempted.

Example

retry_log:
  - msg: "Retrying..."
    level: warn

retry

Configure automatic retry behavior.

Example

retry:
  attempts: 3           # Number of retry attempts
  delay: 1000           # Delay between retries (ms)
  exponential_backoff: true

lookup

Name of a lookup configuration to use for pre-fetching data.

Example

lookup: user_lookup

item_timeout

Per-item execution timeout for lookup iterations. Controls how long each individual item in the lookup array is allowed to run. Use timeout to cap the total loop duration.

Example

item_timeout: 30s

lookup_concurrency

Maximum number of lookup items to execute concurrently. Defaults to 10. Capped at 50 in managed run modes.

Example

lookup_concurrency: 20

lookup_partition

Separate per-item successes from failures in the lookup output. When true, the action returns { "succeeded": [...item data...], "failed": [{ item, http_code?, error?, data? }] } instead of a flat array, so a poller can advance its cursor / mark items seen only for successes and let failed items be retried on the next run. Failed items are those whose iteration returned an HTTP code >= 400 or timed out.

Example

lookup_partition: true

lookup_inherit_jq

JQ transformations to apply to lookup results.

Example

lookup_inherit_jq:
  token: .result.token

lookup_inherit

Fields to inherit from lookup results.

Example

lookup_inherit:
  api_key: lookup.api_key

actions

Nested actions for lookup.

Example

actions:
  - name: GetToken
    http:
      url: https://auth.example.com

json_output

Capture specific JSON values from output.

Example

json_output:
  user_id: .data.id

command

Execute a system command.

Example

command:
  run: "echo hello"
  shell: bash

output_stdout

Include command stdout in output.

Example

output_stdout: true

http

HTTP request configuration.

Example

http:
  url: https://api.example.com
  method: POST
  headers:
    Content-Type: application/json
  body:
    key: value

database

Database name for SQL operations.

Example

database: main
query: SELECT * FROM users

google

Google API integration.

Example

google:
  credential: my_google_cred
  get_signed_upload_url:
    bucket: my-bucket
    key: file.txt

aws

AWS service integration.

Example

aws:
  credential: my_aws_cred
  get_signed_upload_url:
    bucket: my-bucket
    key: file.txt

state

Persistent state operation (durable key/value): polling cursors, dedupe sets, idempotency keys, counters. Backed by a pluggable backend (in-memory for local single-node, Postgres for durable/shared, the AirPipe backend in managed mode). Read state inline with a|state::KEY|.

Example

state:
  advance:
    key: last_seen
    value: a|Fetch::max_updated_at|

delay

Pause for a fixed duration before continuing — pacing / throttling between steps. Accepts a duration string ("2s", "500ms", "1m") or a number of milliseconds. Bounded by AIRPIPE__MAX_DELAY_SECS (default 300s); longer values are rejected. This is an in-process wait, not a durable long-running delay.

Example

delay: "2s"

email

Email sending action.

Example

email:
  from: [email protected]
  to: [email protected]
  subject: Hello
  text: Body text

emit_metric

Emit a Prometheus metric as part of this action step. Requires expose_metrics: true on the parent config.

Example

- name: TrackRevenue
  emit_metric:
    name: revenue_total
    type: gauge
    value: a|OrderAction::amount|
    labels:
      tier: a|OrderAction::tier|

action

Action identifier for referencing outputs.

Example

action: ValidateUser
# Reference later: a|ValidateUser::result|

depends_on

Run this action when specified actions complete. Can be a list of action names or a RunCondition config.

Example - Simple list

depends_on:
  - LoginBody
  - InputValidation

Example - Config with at_least

depends_on:
  at_least: 1
  actions:
    - OptionalStep1
    - OptionalStep2

run_when_succeeded

Run this action when specified actions succeed.

Example

run_when_succeeded:
  - PreviousAction

run_when_failed

Run this action when specified actions fail.

Example

run_when_failed:
  - MainAction

run_on_assertion

Run this action based on assertion results.

Example

run_on_assertion:
  tests:
    - jq: .valid
      is_equal_to: true

params

Parameters for SQL queries.

Example

params:
  - a|body::user_id|
  - "pending"

post_transforms

Transformations to apply to action output.

Example

post_transforms:
  - extract_with_jq: ".[0]"

name

Action identifier/name.

Example

name: GetUserDetails

description

Description of the action.

Example

description: "Fetches user details"

query

SQL query for database actions.

Example

query: SELECT * FROM users WHERE id = $1

multi

Run this action's query as a multi-statement batch (Postgres only).

The native driver prepares every query, and a prepared statement can hold only one command — so a query with several ;-separated statements (e.g. a schema/seed block) normally fails with SQLSTATE 42601. Set multi: true to run it via the simple protocol instead, which executes all statements. Only valid for queries with no params (a batch cannot be parameterized); it returns an empty result set.

Example

multi: true
query: |
  CREATE TABLE IF NOT EXISTS a (id int);
  CREATE TABLE IF NOT EXISTS b (id int);

url

URL for HTTP actions.

Example

url: https://api.example.com/users

conn_string

Database connection string override.

Example

conn_string: postgresql://user:pass@host:5432/db

output

Output destination handler.

Example

output: http

assert

Validation and response configuration.

Example

assert:
  tests:
    - jq: .status
      is_equal_to: "success"
  success_message: "OK"
  error_message: "Failed"

document_operation

Document database operations.

Example

document_operation:
  database: users_db
  collection: profiles
  operation: insertOne
  insert:
    name: test

hide_action

Hide entire action data.

Example

hide_action: true

hide_data_on_success

Hide action data on success.

Example

hide_data_on_success: true

hide_data_on_error

Hide action data on error.

Example

hide_data_on_error: true

hide_data_on_empty

Hide action data when empty.

Example

hide_data_on_empty: true

hide_errors

Hide error details.

Example

hide_errors: true

hide_metrics

Disable metrics collection.

Example

hide_metrics: true

response_on_success

Custom response on success.

Example

response_on_success:
  http_code: 200
  body:
    status: success

response_on_error

Custom response on error.

Example

response_on_error:
  http_code: 500
  body:
    status: error

ActionResponse

Field	Type	Description
`http_code`	number (nullable)
`headers`	object (nullable)
`body`	string (nullable)

Retry

Field	Type	Description
`attempts`	number	Required.
`delay`	number (nullable)
`exponential_backoff`	boolean (nullable)

LogMessage

Field	Type	Description
`msg`	string	Required.
`level`	string	Required.
`json`	boolean (nullable)

RunCondition

One of:

Array<string>
RunOnConfig

RunOnConfig

Field	Type	Description
`at_least`	number (nullable)
`actions`	Array<string>	Required.
`http_code_on_error`	number (nullable)

ConditionalInput

One of:

Array<string>
Array<ConditionalInputConfig>

ConditionalInputConfig

Field	Type	Description
`input`	string	Required.
`tests`	Array<Test>	Required.

Actions & workflow control

Action​

ActionResponse​

Retry​

LogMessage​

RunCondition​

RunOnConfig​

ConditionalInput​

ConditionalInputConfig​

Action

ActionResponse

Retry

LogMessage

RunCondition

RunOnConfig

ConditionalInput

ConditionalInputConfig