Skip to main content
Automation API

Automation

Use the Automation API to build, version, check and run automations in Tape through code.

Only want to start an automation that already exists in Tape? You build nothing: find its ID and run it.

An automation has a trigger that starts it, an optional filter that decides whether it goes on, and ordered actions that do the work. Each automation belongs to one app.

With this API you can:

  • Discover what an automation can be built from.
  • Create, update and version automations.
  • Validate an automation.
  • Run or simulate an automation on a record.

This API manages the definitions. Each time an automation fires, Tape creates an automation run, which you read through its own endpoints.

Writing JavaScript inside an automation? See Automations for script filters, Perform a calculation and Execute a script.

Working with automations​

PageWhat it covers
QuickstartThe whole lifecycle end to end: discover, create, configure, validate, activate, run, observe.
DiscoveryThe catalog of trigger, action and filter types, with their config schemas.
ManageCreate, retrieve, list, update, replace the trigger, activate, pause and delete.
RevisionsThe version history of an automation.
Run & simulateRun and simulate on a record, and validate a definition.
Advanced / sandboxThe call automation and generate weblink endpoints behind those actions.
Dynamic valuesHow values reference live record and run data.
Reference: object · triggers · filters · actions · errorsThe full object, the lists of types and the error codes.

Run an existing automation​

Start an automation that someone already built in Tape. You need the Admin role in the app's workspace and a personal access token with the capabilities Read automations (automations:read) and Run automations (automations:run).

1. Find the automation ID. List the automations you administer. query keeps those whose name contains the text, ignoring case.

Request
curl "https://api.tapeapp.com/v1/automation/org?query=lead" \
-H "Authorization: Bearer $TAPE_TOKEN"
Response
{
"total": 1,
"automations": [ { "id": 4021, "app_id": 87, "name": "Email the owner on a new high-priority lead", "paused": false, "broken": false } ],
"cursor": null
}

Each entry is a full automation object. The example is shortened. Keep the id.

Have the automation open in Tape? Its ID is the number after /edit-workflow/ in the address.

2. Run it on a record. The record must be in the automation's app.

Request
curl -X POST https://api.tapeapp.com/v1/automation/4021/manual-run \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "record_id": 5001 }'
Response
{ "message": "Use the automation-run API to poll the run. Based on queueing and limitations, this may be delayed." }

The response is 202 with no run ID. The run has real side effects. The run body depends on the trigger.

3. Check the run. List the runs of the automation and find the one with your triggered_on_record_id.

Request
curl -X POST https://api.tapeapp.com/v1/automation-run/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "limit": 5 }'
Response
{
"total": 1,
"automation_runs": [ { "id": "9001", "automation_id": 4021, "status": "completed", "type": "manual", "triggered_on_record_id": 5001 } ],
"cursor": null
}

The example is shortened. status is pending or running while the run works, then completed, failed or cancelled. Retrieve the run by its id to read the step logs.

Does the automation have to be live?

No, a manual run also starts a paused automation. Only a broken one returns 409. To test without side effects, simulate it.

Want another system to start the automation without a token?

Give the automation a Webhook received trigger and send a POST to its webhook URL. Retrieve the automation to read it from trigger.config.webhook_url. See Connect Google Forms to Tape.

The anatomy of an automation​

PartCardinalityWhat it is
Trigger0 or 1The event that starts the automation: a record is created, a date arrives, a schedule fires, a webhook comes in, and so on. See Triggers.
Filter0 or 1A recursive and/or tree of conditions the triggering record must match. Omitted or null means the automation runs every time. See Filters.
Actions0 or moreAn ordered list of steps: send an email, create a record, branch, loop, and so on. See The action object.

The discovery endpoints serve the live catalog of trigger types, action types and filter operators, with the exact config each one accepts. Build against it instead of hard-coding the list: new types show up there without an API change.

Coming from Podio?

A Podio flow or a Globiflow flow becomes an automation. Field references use the field_id, not the external_id. See Move your flows for the trigger and action of each flow step.

Authentication and permissions​

Which credential and capability do I need?

Every endpoint on this resource needs a credential that acts on behalf of a user: a personal access token, an OAuth access token or a user API key. A token also needs the matching capability from the table below. See Capabilities.

CapabilityEndpoints
automations:readDiscovery, retrieve, list, revisions, validate
automations:editCreate, update, replace the trigger, activate, pause, delete
automations:runRun, simulate, and the two Advanced / sandbox endpoints

For the endpoints on Manage, Revisions and Run & simulate, you need the Admin role in the app's workspace. That workspace must be in your own organization. A personal access token also needs the app in its content access.

Can I use an automation API key?

Only on the discovery endpoints and the two Advanced / sandbox endpoints (call automation and generate weblink). Everywhere else it returns 401, because an automation API key authenticates an automation, not a person. The error message names only the user API key (Automations can only be retrieved with a user API key.), but a personal access token or an OAuth access token works too.

Discovery is the exception​

The three discovery endpoints (meta/trigger, meta/action, meta/filter) return a static catalog that is the same for everyone. They have no workspace scope. A token still needs automations:read.

Unavailable automations return 404​

Tape IDs are unique across all organizations. Every automation you can't use returns the same 404, so the API never reveals which IDs exist. That covers an automation that doesn't exist, was deleted, is an unsaved draft, is in a workspace you don't administer, or is outside your personal access token's content access.

The automation object​

The automation object lists every property with an example. Triggers, Filters and Actions describe each part.

Config values can pull in live record data through dynamic values.

The object page also explains the broken flag. Errors & broken reasons lists every code in broken_reason.

Status and lifecycle​

An automation has no single status field. Its state is the pair of booleans paused and broken:

pausedbrokenMeaning
falsefalseLive. The automation runs when its trigger fires.
truefalsePaused. A valid automation that its trigger doesn't fire. You can still run or simulate it manually.
anytrueBroken. The definition can't run, so it doesn't.
  • A new automation starts paused and not broken: a valid draft that you set up and then activate.
  • Activate checks the definition again and refuses a broken one with 409. Pause succeeds every time.
  • Every change creates a new, unchangeable revision.

Identifiers and timestamps​

Most IDs on this resource are plain JSON integers: id, app_id, workspace_id, and the automation_id in a path. Two are strings:

  • A revision ID is a 64-bit value, returned as a string so any language can handle it safely.
  • Action ids are opaque. Treat them as handles, not numbers.

All timestamps use the Tape API datetime format YYYY-MM-DD HH:mm:ss, with no T separator, no Z suffix and no milliseconds. A plain timestamp such as created_at is in your timezone, and its _utc twin holds the same instant in UTC. See Date & timezone.

Rate limit credits​

EndpointsCost
The list endpoints (app, workspace, organization)2x base credits
Everything else: discovery, retrieve, create, update, lifecycle, revisions, validate, run, simulate1x base credits

These request credits are separate from the automation action credits that a real run uses and reports as num_consumed_actions. Runtime limits, such as the cap on actions per run, the cap of 1000 records per collection and the shared email quota, are on Limits and throttling.

Errors​

Errors use the standard envelope: status_code, endpoint, error_code and error_message. On this resource:

  • A malformed body, a path ID that isn't an integer, or a run body that doesn't match the trigger returns 400.
  • A credential that doesn't act on behalf of a user, where the endpoint needs one, returns 401.
  • A token without the capability the endpoint needs returns 403. See Capabilities.
  • An automation, app, workspace, revision or record that isn't available to you returns 404. See Unavailable automations return 404.
  • Activating, running or simulating a broken automation returns 409.

See Errors & broken reasons for the Automation API and Errors for all error codes.

Next steps​