Automations

The rule engine turns an event into work, and it now lives on the v1 contract. A rule listens to one event type, a condition decides whether that particular event is its case, and an ordered list of actions runs — eighteen operations across fifteen routes under /v1/automations, all behind the new automations module. Start with the Automations guide.

• Ask the catalog, do not guess — GET /v1/automations/catalog returns the triggers your company can subscribe to (already filtered by the modules your plan includes), the closed set of condition operators and combinators, and the actions that have a registered adapter. The evaluable fields of a trigger are a deliberate second call, GET /v1/automations/catalog/triggers/{trigger}/fields, so the catalog stays small enough to cache and diff.
• Every edit seals a version — editing a rule never rewrites its previous definition: it seals a new version and bumps current_version, and every run keeps a pointer to the exact version it executed. A rule is born draft and hears nothing until you activate it.
• A dry run that materialises nothing — POST /v1/automations/rules/{rule}/dry_run answers what a rule would do against a sample event: no e-mail leaves, no webhook is delivered, no entity is mutated, no run row is written, and neither the monthly budget nor the engine's frequency limit is consumed. A condition that cannot be evaluated comes back as condition_error with a 200, because seeing why a rule cannot be evaluated is the point.
• Run history, steps and replay — every admitted event produces a run and every action a step, both carrying the frozen definition and the trigger payload. discard_reason is a typed value from a closed catalog, so you can branch on it instead of parsing text. Parked work is rearmed with POST /v1/automations/runs/{run}/replay or its per-step sibling; the replay executes for real and is marked x-irreversible in the spec.
• Four guardrails, and blocked is not failed — chain depth (three hops "action → event → rule" by default), a per-minute frequency limit, the monthly budget of the plan (GET /v1/automations/usage) and an automatic pause after a streak of failed runs. A run stopped by any of them is recorded as blocked with its typed reason. See Automations error codes — 47 new codes under the Automations group, each with its cause and what to do.
• Four fine-grained scopes — automations:read, automations:write, automations:delete and automation_runs:read. Reading and writing rules and reading the run history are grantable on the OAuth consent screen; deleting a rule is not, and stays API-key-only. Reading the rule book and reading what the rules actually did are separate on purpose. See Scopes & permissions.
• Seven life-cycle events, and they are triggers themselves — automation_rule.activated, .paused, .auto_paused, automation_run.started, .completed, .failed and .step_dead_lettered. They live in the same closed catalog as every other event, so an automation can react to automation_run.failed exactly as it reacts to invoice.paid; chaining is bounded by the chain-depth cap, not forbidden. See Events.
• Portfolio rules for accounting firms — a rule declares which companies it watches in its scope field: empresa (the default) watches its own company, cartera watches every client company a firm manages and delivers the notice to the firm. The scope is immutable, and only the four notifying action types are accepted in cartera — the other four would take a document of the managed company as their subject.
• MCP and CLI parity — the same surface as 18 MCP tools (catalog) and as the factuarea automations command group (CLI).