# Automations > A trigger and the steps it runs: actions, waits and conditions, with their run history. 11 REST endpoints with parameters, permissions and curl examples. Canonical: https://ballast.to/docs/api/automations [API reference](https://ballast.to/docs/api) A trigger and the steps it runs: actions, waits and conditions, with their run history. 11 endpoints, each also a tool for your AI through [MCP](https://ballast.to/docs/mcp). Authentication and errors are on the [overview](https://ballast.to/docs/api#authentication). ## What an automation can be built from GET /api/v1/automations/options Triggers, actions and condition fields with their operators, the text variables each trigger has ({{lead.first\_name|there}}), the recipes, and this workspace's labels, lists, campaigns, webhook endpoints and custom fields to refer to by id. MCP tool get\_automation\_options Read-only Returns - **`triggers` required object\[\]** - **`actions` required object\[\]** - **`fields` required object\[\]** - **`leadStatuses` required string\[\]** - **`providers` required string\[\]** - **`recipes` required object\[\]** - **`limits` required object** - **`refs` required object** cURL ``` curl https://ballast.to/api/v1/automations/options \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## List automations GET /api/v1/automations Each with its trigger, steps, setup issues and run counts for the last 30 days. MCP tool list\_automations Read-only Returns - **`automations` required object\[\]** cURL ``` curl https://ballast.to/api/v1/automations \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## Get an automation GET /api/v1/automations/{id} MCP tool get\_automation Read-only Parameters - **`id` required path · string** Returns - **`automation` required object** - **`refs` required object** cURL ``` curl https://ballast.to/api/v1/automations/ \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## Create an automation POST /api/v1/automations Starts turned off. Give a trigger and steps, or a recipeId from get\_automation\_options (its trigger and steps, with ids to fill in where it names a campaign or list). Turn it on with update\_automation once it has no issues. MCP tool create\_automation Owners and admins Parameters - **`name` required string** - **`trigger` object** - **`steps` object\[\]** - **`recipeId` string** Returns - **`id` required string** - **`name` required string** - **`trigger` required object** - **`steps` required object\[\]**: The flow under the trigger. A condition is the last step of its path and holds \`yes\` and \`no\` paths. - **`enabled` required boolean** - **`issues` required object\[\]**: What keeps it from being turned on, in reading order - **`stepCount` required number** - **`runs` required number** - **`failed` required number** - **`inProgress` required number**: Runs waiting or running right now - **`lastRunAt` required string | null** - **`hook` required object | null**: Inbound webhook trigger only - **`createdAt` required string** - **`updatedAt` required string** cURL ``` curl -X POST https://ballast.to/api/v1/automations \ -H "Authorization: Bearer $BALLAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":""}' ``` ## Change an automation, or turn it on or off PATCH /api/v1/automations/{id} Send only what changes. \`steps\` replaces the whole flow. Turning it on is refused while it has setup issues; turning it off, or changing the trigger, ends its runs in progress. A flow saved while it's on can't have issues. MCP tool update\_automation Owners and admins Parameters - **`id` required path · string** - **`name` string** - **`trigger` object** - **`steps` object\[\]** - **`enabled` boolean** Returns the same fields as Create an automation. cURL ``` curl -X PATCH https://ballast.to/api/v1/automations/ \ -H "Authorization: Bearer $BALLAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"","trigger":{}}' ``` ## Delete an automation DELETE /api/v1/automations/{id} Its runs in progress stop and its history goes with it. MCP tool delete\_automation Owners and admins MCP asks to confirm Parameters - **`id` required path · string** Returns - **`ok` required true** cURL ``` curl -X DELETE https://ballast.to/api/v1/automations/ \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## Duplicate an automation POST /api/v1/automations/{id}/duplicate The copy starts turned off. MCP tool duplicate\_automation Owners and admins Parameters - **`id` required path · string** Returns the same fields as Create an automation. cURL ``` curl -X POST https://ballast.to/api/v1/automations//duplicate \ -H "Authorization: Bearer $BALLAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` ## An automation's run history GET /api/v1/automations/{id}/runs Newest first, 50 at a time (pass \`cursor\` from the last answer). Each run lists the steps it went through and what happened at each. Kept 90 days. MCP tool list\_automation\_runs Read-only Parameters - **`id` required path · string** - **`status` query · "running" | "waiting" | "done" | "failed" | "canceled"** - **`cursor` query · string** - **`limit` query · integer** Returns - **`runs` required object\[\]** - **`nextCursor` required string | null** cURL ``` curl https://ballast.to/api/v1/automations//runs \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## List a connected CRM's deal pipelines and stages GET /api/v1/automations/crm/{provider}/pipelines Read live from HubSpot or Pipedrive with the workspace's key, for the pipelineId and stageId of a create-a-deal step. MCP tool list\_crm\_pipelines Read-only Parameters - **`provider` required path · "hubspot" | "pipedrive"** cURL ``` curl https://ballast.to/api/v1/automations/crm//pipelines \ -H "Authorization: Bearer $BALLAST_API_KEY" ``` ## Replace an inbound webhook URL POST /api/v1/automations/{id}/hook/replace For an automation with the Inbound webhook trigger: a new secret, and the old URL stops working at once. Update it wherever it was pasted. MCP tool replace\_automation\_webhook\_url Owners and admins Parameters - **`id` required path · string** Returns the same fields as Create an automation. cURL ``` curl -X POST https://ballast.to/api/v1/automations//hook/replace \ -H "Authorization: Bearer $BALLAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Test an automation without changing anything POST /api/v1/automations/{id}/test Walks the flow once (the saved one, or \`trigger\` and \`steps\` you pass) on sample data: a made-up lead (Jane Doe at Example Co) and, for an inbound webhook, \`payload\` (else the last request the URL received). Pass \`leadId\` or \`leadEmail\` to test on a real lead instead; conditions then read that lead as it is now. Actions say what they would do, waits are passed over, nothing is sent or changed. AI steps and Ask AI run for real. MCP tool test\_automation Owners and admins Parameters - **`id` required path · string** - **`trigger` object** - **`steps` object\[\]** - **`leadId` string** - **`leadEmail` string**: Or pick the lead by its email - **`payload` object** Returns - **`status` required "done" | "failed"** - **`error` required string | null** - **`about` required string**: What the test ran on - **`leadEmail` required string | null** - **`steps` required object\[\]** cURL ``` curl -X POST https://ballast.to/api/v1/automations//test \ -H "Authorization: Bearer $BALLAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{"trigger":{},"steps":[]}' ```