Durable state

StateAction

A persistent state operation. State is durable key/value used for things like polling cursors, dedupe sets, idempotency keys and counters — distinct from var:: variables, which are read-only config/secrets.

It is backed by a pluggable backend selected by deployment: in-memory (local single-node, ephemeral), Postgres (durable/shared, BYO via global.databases), or the AirPipe backend (managed). Redis is a planned backend.

Read state inline anywhere interpolation runs with a|state::KEY| or a|state::NAMESPACE.KEY|. The default namespace is the config name.

Example — read a cursor, fetch since it, advance it

actions:
  - name: Cursor
    state:
      get:
        key: last_seen
        default: "1970-01-01T00:00:00Z"
  - name: Fetch
    http:
      url: "https://api.example.com/items?since=a|state::last_seen|"
  - name: SaveCursor
    state:
      advance:
        key: last_seen
        value: a|Fetch::max_updated_at|

One of:

• get → StateGet — Read a value by key. Output: { "value": <v>, "version": <n>, "found": <bool> }. Returns default (or null) when the key is absent or expired.
• set → StateSet — Upsert a value. Last-write-wins unless expected_version is set (optimistic concurrency — the write fails with a conflict if the stored version differs). Output: `{ "version":…
• advance → StateSet — Monotonically advance a cursor: stores max(current, value). Numeric values are compared numerically; otherwise lexically (works for ISO-8601 timestamps). Never moves a cursor…
• delete → StateGet — Delete a key. Output: { "deleted": <bool> }.
• seen → StateSeen — Check-and-add an id to a bounded dedupe set. Returns whether the id was new (i.e. not seen before). Output: { "was_new": <bool> }.

StateGet

Field	Type	Description
key	string	Required. State key.
namespace	string (nullable)	Optional namespace. Defaults to the config name.
default	any	Value to return when the key is absent or expired.

StateSet

Field	Type	Description
key	string	Required. State key.
value	any	Required. Value to store.
namespace	string (nullable)	Optional namespace. Defaults to the config name.
ttl	string (nullable)	Optional time-to-live, e.g. "1h", "30m", "7d". Omit for no expiry.
expected_version	number (nullable)	Optimistic concurrency: only write when the stored version matches this value. Use 0 to require the key not to exist yet. Ignored by advance.

StateSeen

Field	Type	Description
key	string	Required. Key identifying the dedupe set (e.g. the trigger/source name).
id	string	Required. The id to check and record (e.g. a record id or content hash).
namespace	string (nullable)	Optional namespace. Defaults to the config name.
ttl	string (nullable)	Optional time-to-live for the set, e.g. "7d".