Automation Tools

Create, inspect, and manage automations and their runs. An automation you create here is owned by the agent you connect as and runs with that agent’s permissions. Approval happens in the web app: the automation doesn’t run until someone reviews its tool list there and clicks Approve automation. See Automations concepts for how automations run and their lifecycle.

Automations

createAutomation

Create an automation. It’s prepared automatically: when preparation succeeds it waits at Pending Approval; when it fails, the status is Evaluation Failed or Code Generation Failed, and the automation’s page in the web app says why (see the lifecycle). Permission: automations:write Parameters:

Name	Type	Required	Description
`name`	string	Yes	The automation’s name. Unique among the business’s automations.
`instructions`	string	Yes	When it runs and what it does, in plain English. The trigger is read from this text.
`description`	string	No	A description of what the automation does
`enabled`	boolean	No	Defaults to `true`. Approval in the web app sets this to `true`, even if created disabled.
`maxExecutions`	integer	No	Run limit. The automation moves to Completed when a run reaches it.
`expiresAt`	string (ISO 8601)	No	Expiry time. Runs stop after it passes.

The trigger and any schedule come from instructions. agentId is not accepted: the automation belongs to the agent you connect as. Anything else you send is ignored. Returns: The automation object: id, organizationId, name, description, instructions, status, enabled, agentId, grantedTools (the tool names it can use once approved), createdBy, triggerType, triggerEvent, cronExpression, nextRunAt, lastScheduledRunAt, isActive, disabledAt, disabledReason, currentExecutions, maxExecutions, expiresAt, groupId, groupName, groupMetadata, createdAt, updatedAt, and deletedAt.

getAutomation

Get details of a specific automation by ID. Permission: automations:read Parameters:

Name	Type	Required	Description
`automationId`	string (UUID)	Yes	The ID of the automation to retrieve

Returns: The automation object, or null if not found.

listAutomations

List automations with pagination. Permission: automations:read Parameters:

Name	Type	Required	Default	Description
`limit`	number	No	20	Number of automations to return (1-100)
`offset`	number	No	0	Number of automations to skip for pagination

Returns:

{
  "automations": [...],
  "count": 42,
  "limit": 20,
  "offset": 0
}

updateAutomation

Update an automation. All fields are optional except automationId. Permission: automations:write Parameters:

Name	Type	Required	Description
`automationId`	string (UUID)	Yes	The ID of the automation to update
`name`	string	No	Update the name
`description`	string	No	Update the description
`instructions`	string	No	Update the instructions. This regenerates the automation (see below).
`enabled`	boolean	No	Enable or disable the automation
`status`	`paused` \| `active`	No	Pause or resume an automation that is already active or paused
`maxExecutions`	integer	No	Update the run limit
`expiresAt`	string (ISO 8601)	No	Update the expiry time

Changing instructions stops the automation and sends it back through Pending Evaluation — to Pending Approval when preparation succeeds, or to Evaluation Failed / Code Generation Failed when it doesn’t; it doesn’t run again until it’s approved in the web app, and its page there says why preparation failed. The trigger and schedule are re-derived from the new instructions. An automation that has completed or expired keeps the new text without being regenerated. status only pauses or resumes: setting active on an automation that isn’t already active or paused fails with “…cannot be set to active by updating its status; only an active or paused automation can be paused or resumed — approve it instead”. To resume an automation that loop protection paused, click Resume on its web detail page, or send enabled: true and status: "active" together. Approval of a regenerated version also re-enables it. Anything else you send is ignored. Returns: The updated automation object.

deleteAutomation

Delete an automation. It disappears from lists and stops running. Permission: automations:delete Parameters:

Name	Type	Required	Description
`automationId`	string (UUID)	Yes	The ID of the automation to delete

Returns: The deleted automation object.

Executions

getAutomationExecution

Get details of a specific automation run by ID. Permission: automations.executions:read Parameters:

Name	Type	Required	Description
`executionId`	string (UUID)	Yes	The ID of the run to retrieve

Returns: The execution object, or null if not found. It includes success, executionStatus, errorType, errorMessage, executionTimeMs, attemptNumber, maxAttempts, nextRetryAt, isRetryable, and the startedAt, completedAt, createdAt and updatedAt timestamps.

listAutomationExecutions

List automation runs with pagination, optionally filtered by automation ID. Permission: automations.executions:read Parameters:

Name	Type	Required	Default	Description
`automationId`	string (UUID)	No	-	Filter runs by automation ID
`limit`	number	No	20	Number of runs to return (1-100)
`offset`	number	No	0	Number of runs to skip for pagination

Returns:

{
  "executions": [...],
  "count": 17,
  "limit": 20,
  "offset": 0
}

Errors

Errors come back as text: Error: <message> for most failures, Automation not found for a missing ID, and Validation failed for <tool>: … for invalid parameters. The REST API exposes the same automations; POST /v1/automations additionally accepts an agentId. See the API reference.

Next steps

Authentication

How MCP clients authenticate to the server

Getting Started

Agent resources

Automations

createAutomation

getAutomation

listAutomations

updateAutomation

deleteAutomation

Executions

getAutomationExecution

listAutomationExecutions

Errors

Next steps

Authentication

​Automations

​createAutomation

​getAutomation

​listAutomations

​updateAutomation

​deleteAutomation

​Executions

​getAutomationExecution

​listAutomationExecutions

​Errors

​Next steps

Authentication

Automations

createAutomation

getAutomation

listAutomations

updateAutomation

deleteAutomation

Executions

getAutomationExecution

listAutomationExecutions

Errors

Next steps