Automations reference (JSON)

Every trigger, condition and action an automation can use, with copy-pasteable JSON, the limits, and what each error message means.

This is the full grammar for an automation's document — what you see when you open a rule's Edit from the Automations page, and what your AI writes when you ask it for a rule. For the plain-English tour, start with Automations.

One rule, one document. A rule's name, its on/off switch and the Collection it belongs to are not in the JSON — they're properties of the rule itself, edited on the Automations page. The document holds only what the rule does.

Everything below is a closed list. If a rule uses a word that isn't here, it won't save, and you'll be told exactly where.

The document

{
  "version": 1,
  "when": { "changed": "done_1", "to": true },
  "if": { "all": [{ "key": "stage_3", "op": "neq", "value": "done" }] },
  "then": [
    { "op": "set", "key": "stage_3", "value": "done" },
    { "op": "setValueNow", "key": "completed_at_4" }
  ]
}

Three parts: when (what sets it off), if (an optional extra check), and then (what it does — up to 8 actions).

If you paste in an older whole-Collection document — the kind with a "rules" list inside it — you'll be told so directly, rather than left guessing at a pile of shape errors.

Key	Required	Notes
`version`	yes	Always `1`.
`rules`	yes	Up to 16.
`id`	yes	A short slug you choose — letters, digits, `-`, `_`, up to 36 characters. Must be unique in the document.
`name`	no	What you see in the undo toast. Up to 64 characters. Worth writing.
`enabled`	no	Defaults to `true`. Set `false` to park a rule without deleting it.
`when`	yes	Exactly one trigger.
`if`	no	An extra gate.
`then`	yes	1–8 actions.

The key in a condition or action is a binding key — the short name of a property on this Collection, like done_1 or stage_3. You can see them on the Collection's Properties tab.

Triggers (`when`)

Exactly one per rule.

`changed`

{ "changed": "done_1", "to": true }

Field	Notes
`changed`	The property to watch.
`to`	Optional. Only fire when the new value is this.
`from`	Optional. Only fire when the old value was this.

With neither to nor from, any change to that property fires the rule.

Dragging a card between board columns changes the property the board groups by, so this trigger covers board drags with nothing extra:

{ "changed": "stage_3", "to": "done" }

`created`

{ "created": true }

Fires once, when an entry is created, after its defaults are filled in. Takes no to or from.

Conditions (`if`)

Optional. Same grammar as conditional card styling, so there's one condition language to learn:

{ "if": { "all": [ { "key": "stage_3", "op": "neq", "value": "done" } ] } }

all — every condition must hold.
any — at least one must hold. Leave any out and it isn't checked.

You can use both; then all of all must hold and at least one of any.

Operator	Means	Needs a value
`eq`	is	yes
`neq`	is not	yes
`gt` `gte`	greater than / or equal	yes
`lt` `lte`	less than / or equal	yes
`contains`	text contains (ignores capitals)	yes
`empty`	has no value	no
`present`	has a value	no

A value is one plain thing: text (up to 64 characters), a number, or true/false. Never a formula.

Actions (`then`)

Between 1 and 8. They run in the order you write them.

These are the same verbs a card button runs — see the commands reference. One vocabulary, wherever you write it.

Verb	Needs `value`	What it does
`setValue`	yes	Writes the value.
`setValueNow`	no	Stamps a date or datetime property with the current moment.
`clearValue`	no	Empties the property.
`toggleValue`	no	Flips a checkbox — anything not already ticked becomes ticked.
`incrementValue`	no	Adds to a number. Optional `by` (default `1`, negative counts down). An unset number counts as zero.
`addTag`	yes	Adds one tag, leaving the property's other tags alone.
`removeTag`	yes	Removes one tag, leaving the others alone.

[
  { "op": "setValue",       "key": "stage_3", "value": "done" },
  { "op": "setValueNow",    "key": "completed_4" },
  { "op": "clearValue",     "key": "blocked_by_7" },
  { "op": "toggleValue",    "key": "done_1" },
  { "op": "incrementValue", "key": "attempts_9", "by": 1 },
  { "op": "addTag",         "key": "tags_5", "value": "shipped" },
  { "op": "removeTag",      "key": "tags_5", "value": "blocked" }
]

Tag values: write the name, we remember the option

Write the tag's name, exactly as you'd say it:

{ "op": "set", "key": "stage_3", "value": "done" }

When you save, the name is swapped for that option's permanent id and stored as tag_id:

{ "op": "set", "key": "stage_3", "tag_id": "4f9c…" }

That's why renaming a tag can never stop a rule from working — the rule points at the option itself, not at what it happens to be called today. Reopen the rule and you'll see the current name again, because the editor translates back every time.

If two options in the same list share a name, we won't guess between them — you'll get an error asking you to pick one, and you can paste the option's tag_id directly instead.

The same tag_id field works in a condition ({ "key": "stage_3", "op": "eq", "tag_id": "4f9c…" }) and in a trigger ("to_tag_id" / "from_tag_id" beside when), and in a card layout's conditional rules. A field carries either a value or a tag_id — never both.

Limits

Limit	Value
Rules per Collection	16
Actions per rule	8
Conditions per `all` / `any` list	8
Text value length	64 characters
Rule name length	64 characters
How far a cascade runs	3 steps
Whole document size	16 KB

What happens when it can't save

Nothing is written — not part of it, none of it — and you get a list of exactly what's wrong, each pointing at the spot:

rules[0].then[0].op: "notify" is not an action
  (expected setValue | setValueNow | clearValue | toggleValue | incrementValue | addTag | removeTag)

Common ones:

Message	Means
`names no trigger`	The `when` has neither `changed` nor `created`.
`is required for "set"`	That verb needs a `value`.
`not allowed for "setValueNow"`	That verb takes no `value`.
`duplicate rule id`	Two rules share an `id`.
`…completes a cycle back to a rule that triggers on it`	Rule A sets off rule B which sets off rule A. Break the loop, or gate one with an `if`.
`is not a property reference`	The `key` isn't a valid binding key. Check the Properties tab.

Rules of thumb

A rule fires at most once per edit. It can't set itself off, even indirectly.
A rule that would change nothing does nothing — no toast, no write. Setting Stage to done when it's already done is silently skipped.
Rules run on your own edits, on any of your devices. Your AI's edits in a chat don't set them off.

Automations reference (JSON)

The document

Triggers (when)

changed

created

Conditions (if)

Actions (then)