Automation
Not final
While the Automation API is in beta, the endpoints, payloads and behaviour described on these pages may change, or be withdrawn, at any time without notice. Use at your own risk, and pin nothing you cannot change.
An automation is made up of a trigger that starts it, an optional filter that decides whether to proceed, and an ordered list of actions that it runs — all scoped to a single app. This API lets you discover what an automation can be built from, create and version automations, validate them, and run or simulate them against a record.
Automations live above their executions. Each time an automation fires it produces an automation run; this API manages the definitions, and you read their executions through the existing Automation Run resource.
This overview covers the concepts, the shared authentication rules, the shape of the automation object, and the resource-wide conventions. The individual endpoints live on the pages listed under Working with automations.
The anatomy of an automation
| Part | Cardinality | What it is |
|---|---|---|
| Trigger | 0 or 1 | The event that starts the automation — a record being created, a date arriving, a schedule, an inbound webhook, and so on. See the trigger object. |
| Filter | 0 or 1 | A recursive and/or tree of conditions the triggering record must match. Omitted or null means the automation always runs. See filters. |
| Actions | 0 or more | An ordered list of steps — send an email, create a record, branch, loop, and so on. See the action object. |
The catalog of available trigger types, action types and filter operators — and the exact config each one
accepts — is served live by the discovery endpoints. Build against those
rather than hard-coding the vocabulary: new types appear there without a change to this API. The full token lists are
also collected in the reference pages.
Authentication and permissions
Requires a user API key
Every endpoint on this resource requires a user API key, with two exceptions: the
discovery endpoints and the two Advanced / Sandbox
endpoints (call-automation and generate-weblink) each accept either a user or an automation API key. Everywhere
else, an automation API key authenticates an automation, not a person, and therefore carries no workspace role to
check; using one there returns a 401. See Authentication.
You may work with the automations of any app in a workspace you administrate. Concretely, for every automation-scoped call the caller must be an administrator of the workspace the automation's app belongs to, and that workspace must be in your own organization.
Discovery is the exception
The three discovery endpoints (meta/trigger, meta/action,
meta/filter) return a static catalog that is identical for everyone. They require only a valid API key of
either kind and carry no workspace scope.
Unavailable automations return 404
Tape IDs are globally unique, so an ID belonging to another organization is still a perfectly well-formed ID. To
avoid turning these endpoints into a way of probing which IDs exist, every automation that is not available to you
answers the same 404 — whether it does not exist, was deleted, is an unsaved draft, or lives in a workspace you do
not administrate. A request authenticated with the wrong kind of key still returns 401, and a malformed ID (one
that is not an integer) returns 400.
The automation object
A single retrieve returns the automation wrapped under automation. Create, update, activate, pause and delete
return the automation in the same envelope, so the shape below is the one you will handle throughout the resource.
{
"automation": {
"id": 4021,
"app_id": 87,
"workspace_id": 12,
"name": "Email the owner on a new high-priority lead",
"description": "Notifies the record owner whenever a lead is created.",
"paused": false,
"broken": false,
"broken_reason": null,
"trigger": {
"type": "record_created",
"config": { "app_id": 87 }
},
"filter": null,
"actions": [
{
"id": "3f9a2c",
"type": "send_email",
"group": "action",
"config": {
"subject": ["A new lead was created"],
"smtp_account_id": 5
}
}
],
"created_at": "2024-05-14 09:12:31",
"updated_at": "2024-05-20 16:03:08"
}
}
Fields
| Field | Type | Description |
|---|---|---|
id | integer | ID of the automation. |
app_id | integer | The app the automation belongs to. Only database apps can have automations. |
workspace_id | integer | The workspace the app belongs to. |
name | string | Name of the automation. |
description | string | Optional description. Absent when the automation has none. |
paused | boolean | Whether the automation is paused. See Status and lifecycle. |
broken | boolean | Whether the automation's definition is not executable. |
broken_reason | object | null | The reasons the automation is broken, or null when it is not. See Broken reasons. |
trigger | object | null | The single trigger, or null when none is configured. |
filter | object | null | The root filter group — a recursive and/or condition tree. null when the automation has no filter. |
actions | array | The ordered list of actions. An empty array when the automation has none. |
created_at | string | When the automation was created, in UTC. |
updated_at | string | When the automation was last modified, in UTC. |
The trigger object
A trigger is { type, config }. The type is one of the public trigger types;
config holds the trigger's settings, keyed exactly as the trigger's config_schema from
GET /v1/automation/meta/trigger describes.
| Field | Type | Description |
|---|---|---|
type | string | The trigger type, e.g. record_created. |
config | object | The trigger's settings. Keys and value types follow the trigger's config_schema. |
Config values may be dynamic — see Dynamic values.
The filter
The filter is a recursive tree of groups and conditions. A group combines its rows with and or or;
a condition tests a field against an operator. The root group has no id; nested nodes do.
| Field | Type | Description |
|---|---|---|
operator | string | and (match all) or or (match any) — on a group. |
rows | array | A group's children — nested groups or conditions. |
subject | object | On a condition: a reference to the field, record-metadata, trigger-output or action-output being tested. |
operator | string | On a condition: one of the 22 operators, e.g. is, contains, is_any_of. |
value | object | On a condition: the tagged comparison value. Absent for value-less operators such as is_empty. |
The operators valid for a given field type are returned by
GET /v1/automation/meta/filter?field_type=…. See
filters for the full model, including script conditions.
Dynamic values
Wherever a value can reference live data — a trigger/action config field, a filter comparison — it is a dynamic
value: an ordered array that interleaves literal strings with references resolved against the record at run
time. A subject like "the record's Name field" is a reference; "Hi " is a literal. See
Dynamic values for the reference model and the full source/value
vocabularies.
The action object
Each entry in actions is one step. Leaf actions do work (group: "action"); control-flow actions
(group: "control_flow" — a for_loop or a conditional) nest other actions under an action_rows array inside
their config.
| Field | Type | Description |
|---|---|---|
id | string | Stable identifier of the action within the automation. |
type | string | The action type, e.g. send_email. See action types. |
group | string | action for a leaf step, or control_flow for a for_loop / conditional. |
custom_name | string | Optional label for the step. Absent when unset. |
deactivate | boolean | Whether the step is deactivated (skipped). Absent when unset. |
continue_on_error | boolean | Whether the run continues when this step errors. Absent when unset. |
config | object | The action's settings, keyed as the action's config_schema from GET /v1/automation/meta/action describes. Dynamic values inside are normalized to the reference model. For conditional / for_loop, config also carries the branch/loop structure (condition, action_rows, else_action_rows, iterable, break_condition, continue_condition). |
Control-flow shapes
For conditional / for_loop, the branch/loop members live inside config — see
actions for the full structure. Each branch is
gated by presence: an omitted member is disabled.
Broken reasons
When broken is true, broken_reason is an object with an errors array; each entry has a machine-readable
code, an English message, and optional references to the app, field or action at fault. The full list of codes is
on the reference page. To check an automation on demand
rather than reading the stored flag, use validate.
Status and lifecycle
An automation has no single status field. Its state is the pair of booleans paused and broken:
paused | broken | Meaning |
|---|---|---|
false | false | Live — the automation runs when its trigger fires. |
true | false | Paused — a valid automation that is not fired automatically by its trigger. It can still be manually run or simulated. |
| any | true | Broken — the definition is not executable and will not run. |
- A newly created automation lands paused and not broken — a valid draft you configure, then activate.
- Activate re-checks the definition and refuses a broken one with a
409; pause always succeeds. - Every change mints a new immutable revision.
The lifecycle endpoints (create, update, activate, pause, delete) are on the Manage page.
Identifiers and timestamps
Most IDs on this resource are plain JSON integers (id, app_id, workspace_id, and the automation_id you
pass in a path). The one exception is a revision ID, which is a 64-bit value returned as a string so it is
safe to handle in any language — see revisions. Action ids are opaque
strings; treat them as handles, not numbers.
All timestamps use the Tape API datetime format — UTC, YYYY-MM-DD HH:mm:ss, with no T separator, no Z suffix and
no milliseconds. See Date & Timezone.
Rate limit credits
| Endpoints | Cost |
|---|---|
| The list endpoints (app, workspace, org) | 2x base credits |
| Everything else — discovery, retrieve, create, update, lifecycle, revisions, validate, run, simulate | 1x base credits |
This is separate from the automation action credits a real run
consumes as it executes (reported as num_consumed_actions on the resulting run). See
Request limits for how rate limiting works. Runtime limits — the per-run action cap, the
1000-record collection cap, and the shared email send quota — are covered under
Automations → Limitations.
Errors
Errors use the standard envelope — status_code, endpoint, error_code and error_message. Across this resource:
400— a malformed body or a path ID that is not an integer.401— the request is not authenticated with a user API key (where one is required).404— the automation, app, workspace or revision is not available to you (see above).409— a lifecycle conflict, e.g. activating a broken automation.
See Errors for the full list of error codes.
Working with automations
| Page | What it covers |
|---|---|
| Quickstart | The whole lifecycle end to end — discover, create, configure, validate, activate, run, observe. |
| Discovery | The catalog of trigger, action and filter types, with their config schemas. |
| Manage | Create, retrieve, list, update, replace the trigger, activate, pause and delete. |
| Revisions | The immutable version history of an automation. |
| Execution | Run and simulate against a record, and validate a definition. |
| Advanced / Sandbox | The call-automation and generate-weblink endpoints that back those actions. |
| Dynamic values | How values reference live record and run data. |
| Reference — object · triggers · filters · actions · errors | The full object, vocabularies and error codes. |