Start, hide & trigger rules

Version-level start and hide rules, plus per-step triggers, are how content reacts. They reuse conditions and actions. Set them on the version with PATCH …/versions/{id} (startRules, hideRules; triggers live on each step).

Start rules

When the content auto-starts, and how often.

Field	Type	Description
`when`	Condition[]	Auto-start when these match. A full replacement when present; omit it to keep the stored conditions and patch only the settings (frequency / priority / …).
`frequency`	Frequency	How often it may show.
`priority`	`highest` \| `high` \| `medium` \| `low` \| `lowest`	Ordering when several could start at once.
`waitSeconds`	number	Delay in seconds (not ms) before the content becomes eligible after the conditions first match. The countdown survives the conditions un-matching mid-wait, but an elapsed wait guarantees nothing — the conditions are re-checked at show time, and the content starts at the next moment they match again (unlike a trigger wait, which fires its actions regardless). Capped at 300 by the runtime.
`startIfNotComplete`	boolean	Only start if the user hasn’t completed it.

Send startRules: null to clear them.

Frequency

Field	Type	Required	Description
`mode`	`once` \| `multiple` \| `unlimited`	yes	`once` = show a single time; `multiple` = up to N per window; `unlimited` = every time the conditions match. Omitting `frequency` on a write seeds the builder default (`once`) — stored explicitly, visible on read-backs. A version stored with NO frequency (legacy data only) runs with NO limit and re-starts whenever its rules match again.
`every`	`object{ times, duration, unit }`		Re-show window — used by `multiple` (with `times`) and `unlimited`; ignored by `once`. `unit` ∈ `seconds`/`minutes`/`hours`/`days`. Manual and programmatic starts also count toward the `multiple` limit.
`atLeast`	`object{ duration, unit }`		Quiet period: only auto-start if no OTHER content of the SAME type has been shown within this window — and since only flows accept this knob, in practice: no other FLOW. A banner / checklist / launcher showing does NOT block it.

{
  "when": [{ "type": "current_url", "includes": ["/dashboard"] }],
  "frequency": { "mode": "once" },
  "priority": "medium"
}

Hide rules

When to hide the content (even if started). Hiding suspends the session rather than ending it — when the conditions stop matching, the same session reappears at the same step.

Field	Type	Required	Description
`when`	Condition[]	yes	Hide while these match.

Send hideRules: null to clear them.

Step triggers

A step can carry triggers — run actions when conditions become true while the step is showing (e.g. advance when an element appears). Triggers live on the step’s triggers[] (see Content representation).

Field	Type	Required	Description
`when`	Condition[]		Fire when these match.
`do`	Action[]	yes	Actions to run.
`waitSeconds`	number		Delay in seconds (not ms) between `when` matching and `do` firing. The match is latched: the actions fire after the wait even if the conditions have since stopped matching. Capped at 300.

{
  "when": [{ "type": "element", "target": { "selector": "#welcome-modal" }, "state": "present" }],
  "do": [{ "type": "goto_step", "step": "step-2" }]
}

Getting started

Conventions

Concepts

Endpoints

Start rules

Frequency

Hide rules

Step triggers

​Start rules

​Frequency

​Hide rules

​Step triggers

Start rules

Frequency

Hide rules

Step triggers