Manage automations
- cURL
- JSON
curl -X POST https://api.tapeapp.com/v1/automation/app/87 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"name": "Email the owner on a new high-priority lead",
"trigger": { "type": "record_created", "config": {} }
}'
{
"name": "Email the owner on a new high-priority lead",
"trigger": { "type": "record_created", "config": {} }
}
curl https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN"
curl "https://api.tapeapp.com/v1/automation/app/87?limit=2" \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"total": 12,
"automations": [ { "id": 4021, "name": "Email the owner on a new high-priority lead", "paused": false, "broken": false } ],
"cursor": "eyJhbGciOiJI..."
}
curl -X PUT https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "description": "Notifies the owner of new leads." }'
curl -X PUT https://api.tapeapp.com/v1/automation/4021/trigger \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "type": "record_updated", "config": {} }'
curl -X POST https://api.tapeapp.com/v1/automation/4021/activate \
-H "Authorization: Bearer $TAPE_TOKEN"
curl -X POST https://api.tapeapp.com/v1/automation/4021/pause \
-H "Authorization: Bearer $TAPE_TOKEN"
curl -X DELETE https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN"
Use these endpoints to create, read, list, change, activate, pause and delete automations.
Every endpoint returns the automation object, wrapped as { automation }, except the list endpoints.
All endpoints on this page need a credential that acts on behalf of a user: a personal access token, an OAuth access token or a user API key. Retrieve and list need automations:read, all other endpoints need automations:edit (see Capabilities).
You need the Admin role in the app's workspace. Automations you can't use return the same 404. See Authentication and permissions.
Create an automation
Use this endpoint to create an automation in an app.
/v1/automation/app/{app_id}api.tapeapp.com- cURL
- JSON
curl -X POST https://api.tapeapp.com/v1/automation/app/87 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"name": "Email the owner on a new high-priority lead",
"trigger": { "type": "record_created", "config": {} }
}'
{
"name": "Email the owner on a new high-priority lead",
"trigger": { "type": "record_created", "config": {} }
}
The response is 201 with the new automation.
General behavior
- A new automation starts paused and not broken: a valid draft that you finish and then activate.
- Node IDs inside
filterandactionsare optional. Tape creates them when you leave them out. descriptionandtriggerdon't acceptnullhere, unlike in update.- Tape checks create and update bodies against a closed schema. Any top-level property that isn't in the table below returns
400. So does an unknown key inside a trigger'sconfig. - Each action in
actions[]needs bothtypeandconfig. Theconfigcan be an empty{}. An action without aconfigkey returns400.
app_id in a trigger config?Tape accepts a legacy app_id key in a trigger's config, checks that it's an integer (otherwise 400) and drops it unread. The automation's app comes from the automation itself, so a wrong or unknown app_id has no effect. Leave it out in new integrations.
An app can hold at most 500 automations. When an app reaches this limit, Tape rejects further create requests with an error until you delete an automation.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Body parameters
namestringrequired
1 to 5000 characters.
descriptionstring
Up to 25000 characters.
triggerobject
A trigger { type, config }.
filterobject
A filter group.
actionsarray
An ordered list of actions.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | 1 to 5000 characters. |
description | string | no | Up to 25000 characters. |
trigger | object | no | A trigger { type, config }. |
filter | object | no | A filter group. |
actions | array | no | An ordered list of actions. |
Retrieve an automation
Use this endpoint to read one automation with its trigger, filter and actions.
/v1/automation/{automation_id}api.tapeapp.comcurl https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN"
The response is { automation } with its trigger, filter and actions inlined.
Requirements: automations:read, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
List automations
Use these endpoints to list the automations in an app, in a workspace, or in every workspace you administer in your organization.
/v1/automation/app/{app_id}api.tapeapp.com/v1/automation/workspace/{workspace_id}api.tapeapp.com/v1/automation/orgapi.tapeapp.comcurl "https://api.tapeapp.com/v1/automation/app/87?limit=2" \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"total": 12,
"automations": [ { "id": 4021, "name": "Email the owner on a new high-priority lead", "paused": false, "broken": false } ],
"cursor": "eyJhbGciOiJI..."
}
Each entry is a full automation object. The example is shortened.
General behavior
- The
orgvariant takes the organization from your credential. It has no path scope. If you administer nothing, it returns an empty page, not404. - With a personal access token, the
orgvariant lists only automations in apps of the token's content access. Theworkspacevariant needs the whole workspace in the content access. Selected apps alone return404there. - Looking for one automation? Add
querywith part of its name. - Results are sorted oldest first, by ID.
totalis a snapshot taken on the first page.cursorisnullon the last page. See Pagination.- The
cursoris bound to its scope: this app, this workspace or your organization. A cursor sent to a different scope returns400, not an empty page. Send each cursor back only to the list call that produced it.
Requirements: automations:read, and the Admin role in the workspaces you list. Works with a personal access token, an OAuth access token or a user API key.
Query parameters
cursorstring
The cursor of the previous response. Leave it out for the first page.
limitinteger
Page size, 1 to 100. Defaults to 50.
querystring
Only automations whose name contains this text, ignoring case. An empty value returns 400. Leave it out to list all.
| Parameter | Type | Description |
|---|---|---|
cursor | string | The cursor of the previous response. Leave it out for the first page. |
limit | integer | Page size, 1 to 100. Defaults to 50. |
query | string | Only automations whose name contains this text, ignoring case. An empty value returns 400. Leave it out to list all. |
Update an automation
Use this endpoint to change some fields of an automation and keep the rest.
/v1/automation/{automation_id}api.tapeapp.comcurl -X PUT https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "description": "Notifies the owner of new leads." }'
The response is 200 with the whole automation, wrapped as { "automation": { … } }.
General behavior
- This is a partial update. A field you leave out stays unchanged.
- An explicit
nullclearsdescription,triggerorfilter.namecan't benull. actions, when present, replaces the whole list. Send[]to empty it.- Every update that changes the automation creates a new revision.
broken change when I save?broken shows the last verdict Tape stored: create, update, activate and validate never write it, and a failed activate returns 409 with the object unchanged. Call validate for a current verdict. The automation object has the full broken model.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Body parameters (all optional)
namestring
New name, 1 to 5000 characters.
descriptionstring | null
Set, or null to clear.
triggerobject | null
Replace, or null to remove.
filterobject | null
Replace, or null to clear.
actionsarray
Replace the whole list.
| Parameter | Type | Description |
|---|---|---|
name | string | New name, 1 to 5000 characters. |
description | string | null | Set, or null to clear. |
trigger | object | null | Replace, or null to remove. |
filter | object | null | Replace, or null to clear. |
actions | array | Replace the whole list. |
Replace the trigger
Use this endpoint to swap the trigger of an automation.
/v1/automation/{automation_id}/triggerapi.tapeapp.comcurl -X PUT https://api.tapeapp.com/v1/automation/4021/trigger \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "type": "record_updated", "config": {} }'
The response is 200 with the whole automation, wrapped as { "automation": { … } }.
General behavior
- The whole body is the trigger,
{ type, config }. - It replaces any existing trigger and creates a revision.
- To remove a trigger, use update with
trigger: null.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Activate an automation
Use this endpoint to set an automation live.
/v1/automation/{automation_id}/activateapi.tapeapp.comcurl -X POST https://api.tapeapp.com/v1/automation/4021/activate \
-H "Authorization: Bearer $TAPE_TOKEN"
The response is 200 with the whole automation, wrapped as { "automation": { … } }.
General behavior
- No request body.
- Tape checks the definition again on every call. A broken definition returns
409. Usevalidateto see the reasons. - Activating an automation that is already live succeeds and changes nothing, as long as the definition stays valid.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Pause an automation
Use this endpoint to stop the trigger from firing an automation.
/v1/automation/{automation_id}/pauseapi.tapeapp.comcurl -X POST https://api.tapeapp.com/v1/automation/4021/pause \
-H "Authorization: Bearer $TAPE_TOKEN"
The response is 200 with the whole automation, wrapped as { "automation": { … } }.
General behavior
- No request body.
- Pausing twice changes nothing. A broken definition never blocks a pause.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Delete an automation
Use this endpoint to delete an automation.
/v1/automation/{automation_id}api.tapeapp.comcurl -X DELETE https://api.tapeapp.com/v1/automation/4021 \
-H "Authorization: Bearer $TAPE_TOKEN"
General behavior
- This is a soft delete, the same as in Tape. The automation drops out of every list and can't be retrieved, but the data stays.
- The response is
200with the final, soft-deleted automation as confirmation, not204.
Requirements: automations:edit, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Rate limit credits
The three list endpoints cost 2x base credits. Every other endpoint on this page costs 1x. See Request limits.
Errors
- A body with a property the schema doesn't know, an action without
config, a path ID that isn't an integer, or acursorsent to another scope returns400. - A credential that doesn't act on behalf of a user, for example an automation API key, returns
401. - A token without
automations:readorautomations:editreturns403. - An automation, app or workspace that isn't available to you returns
404. This includes automations in workspaces you don't administer and apps outside your personal access token's content access. - Activating a broken automation returns
409.
See Errors & broken reasons for the Automation API and Errors for all error codes.