Automations API¶

Create automations from templates, run them, read their results, and manage schedules. See Automations.

Paths are relative to https://<your-atlas-host>/api/v1. For the API key and headers every request needs, see Authentication.

Endpoint	What it does
GET /automations/	List automations in a workspace
POST /automations/	Create an automation from a library template
GET /automations/templates/	List the automation library templates
POST /automations/workflows/extract/	Extract a replayable workflow from a chat conversation
POST /automations/workflows/	Create an automation (workflow) from a conversation extraction
GET /automations/{automation_id}/	Get an automation by ID
PATCH /automations/{automation_id}/	Update an automation
DELETE /automations/{automation_id}/	Delete an automation
POST /automations/{automation_id}/activate/	Activate an automation so it runs on its schedule
POST /automations/{automation_id}/deactivate/	Pause an automation
POST /automations/{automation_id}/run/	Start a run of an automation now; returns the run id
GET /automations/{automation_id}/runs/	List an automation’s recent runs
GET /automations/{automation_id}/runs/{run_id}/	Get a run, with its status, output and findings
GET /automations/packs/	List automation packs, bundles of templates created together
POST /automations/packs/	Create every automation in a pack in one step
GET /automations/packs/instances/	List automation packs created in the organization
GET /automations/packs/instances/{instance_id}/	Get an automation pack instance by ID
PUT /schedules/	Create or update a schedule for a target
GET /schedules/{target_type}/{target_id}	List all schedules for a target
DELETE /schedules/{target_type}/{target_id}/{task_type}	Delete a schedule
POST /schedules/{schedule_id}/pause	Pause a schedule, keeping its configuration
POST /schedules/{schedule_id}/resume	Resume a paused schedule

List automations¶

GET /automations/

List automations in a workspace.

Parameters

Name	In	Type	Required
`workspace_id`	query	UUID	Yes
`is_active`	query	boolean
`category`	query	string
`trigger_type`	query	string
`source`	query	string
`limit`	query	integer
`offset`	query	integer

Response A list of objects:

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Create an automation from a template¶

POST /automations/

Create an automation from a library template.

Request body

Field	Type	Required	Description
`workspace_id`	UUID	Yes
`template_slug`	string	Yes	A template’s `slug` from `GET /automations/templates/`.
`display_name`	string	Yes
`description`	string
`prompt_parameters`	object		Values for the template’s parameters, keyed by name; missing ones use the template’s defaults.
`trigger_type`	string		`cron` to run on a schedule, `event` to run when a matching event happens.
`cron_expression`	string		Five-field cron schedule in UTC, such as `0 9 * * 1`. Empty uses the template’s default schedule.
`event_patterns`	list of string		For `event` triggers: glob patterns on event names, such as `datasource.*`. Only data source events start automations.
`post_to_chat`	boolean		Post each run’s output and findings to a new chat conversation.
`notify_on_findings`	boolean		Notify the automation’s creator when a run finishes.

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

List automation templates¶

GET /automations/templates/

List the automation library templates.

Response A list of objects:

Field	Type
`slug`	string
`display_name`	string
`description`	string
`category`	string
`icon`	string
`default_cron`	string
`parameter_count`	integer

Extract a workflow from a conversation¶

POST /automations/workflows/extract/

Extract a replayable workflow from a chat conversation.

Request body

Field	Type	Required
`conversation_id`	UUID	Yes

Response

Field	Type
`display_name`	string
`description`	string
`prompt_template`	string
`suggested_tools`	list of string
`parameters`	list of object

Create an automation from a conversation¶

POST /automations/workflows/

Create an automation (workflow) from a conversation extraction.

Request body

Field	Type	Required	Description
`workspace_id`	UUID	Yes
`conversation_id`	UUID	Yes	The chat conversation the workflow comes from.
`display_name`	string	Yes
`description`	string
`prompt_template`	string	Yes	Instructions the agent follows on each run, with `{{ parameter }}` placeholders.
`prompt_parameters`	object		Values for the prompt’s `{{ parameter }}` placeholders, keyed by name.
`suggested_tools`	list of string		Tool names the agent should prefer; unknown names are ignored.
`max_steps`	integer		Stored with the automation; runs do not use it yet.
`trigger_type`	string		`cron` to run on a schedule, `event` to run when a matching event happens.
`cron_expression`	string		Five-field cron schedule in UTC, such as `0 9 * * 1`.
`post_to_chat`	boolean		Post each run’s output and findings to a new chat conversation.
`notify_on_findings`	boolean		Notify the automation’s creator when a run finishes.

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Get automation¶

GET /automations/{automation_id}/

Get an automation by ID.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Update automation¶

PATCH /automations/{automation_id}/

Update an automation.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Request body

Field	Type	Description
`display_name`	string
`description`	string
`icon`	string	A Heroicons icon name, such as `bolt`.
`prompt_template`	string	Instructions the agent follows on each run, with `{{ parameter }}` placeholders. Cannot be changed on template-based automations.
`prompt_parameters`	object	Values for the prompt’s `{{ parameter }}` placeholders, keyed by name.
`custom_prompt_override`	string	A full prompt that replaces the filled-in template. Empty uses the template.
`suggested_tools`	list of string	Tool names the agent should prefer; unknown names are ignored.
`max_steps`	integer	Stored with the automation; runs do not use it yet.
`model_override`	string	AI model for runs, as `model-name` or `provider:model-name`. Empty uses the default.
`trigger_type`	string	`cron` to run on a schedule, `event` to run when a matching event happens.
`cron_expression`	string	Five-field cron schedule in UTC, such as `0 9 * * 1`.
`event_patterns`	list of string	For `event` triggers: glob patterns on event names, such as `datasource.*`. Only data source events start automations.
`post_to_chat`	boolean	Post each run’s output and findings to a new chat conversation.
`notify_on_findings`	boolean	Notify the automation’s creator when a run finishes.

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Delete automation¶

DELETE /automations/{automation_id}/

Delete an automation.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Response

The raw file content.

Activate automation¶

POST /automations/{automation_id}/activate/

Activate an automation so it runs on its schedule.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Deactivate automation¶

POST /automations/{automation_id}/deactivate/

Pause an automation.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`icon`	string
`template_slug`	string
`workspace_id`	UUID
`trigger_type`	string	`cron` or `event`.
`cron_expression`	string
`event_patterns`	list of string
`prompt_template`	string
`prompt_parameters`	object
`custom_prompt_override`	string
`suggested_tools`	list of string
`max_steps`	integer
`model_override`	string
`post_to_chat`	boolean
`notify_on_findings`	boolean
`is_active`	boolean
`is_custom`	boolean	Whether a user wrote the prompt rather than a template.
`source`	string	How it was created: `template`, `custom`, or `conversation`.
`source_conversation_id`	UUID
`pack_instance_id`	UUID
`last_run_at`	datetime
`last_run_status`	string	`completed` or `failed` for the latest finished run; empty if never run.
`run_count`	integer
`consecutive_failures`	integer	Failed runs in a row. At 5 the automation pauses; activating it resets this.
`created_at`	datetime
`updated_at`	datetime

Run an automation now¶

POST /automations/{automation_id}/run/

Start a run of an automation now; returns the run id.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes

Response

Field	Type
`run_id`	UUID
`status`	string

List automation runs¶

GET /automations/{automation_id}/runs/

List an automation’s recent runs.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes
`limit`	query	integer

Response A list of objects:

Field	Type	Description
`id`	UUID
`automation_id`	UUID
`task_execution_id`	UUID
`trigger_type`	string	What started the run: `cron`, `event`, or `manual`.
`trigger_event`	string	The event that started the run; empty otherwise.
`prompt_snapshot`	string	The prompt exactly as the run used it.
`output`	string	The run’s written result.
`findings`	list of object	Issues the run recorded, each with `severity` (`critical`, `warning`, `info`), `title`, `impact`, and `action`.
`tool_calls`	list of object
`token_usage`	object
`duration_ms`	integer
`conversation_id`	UUID
`status`	string	`pending`, `running`, or `waiting` while in progress; then `completed`, `failed`, `timed_out`, `cancelled`, or `dlq` (retries used up).
`error_message`	string
`created_at`	datetime
`updated_at`	datetime

Get an automation run¶

GET /automations/{automation_id}/runs/{run_id}/

Get a run, with its status, output and findings.

Parameters

Name	In	Type	Required
`automation_id`	path	UUID	Yes
`run_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`automation_id`	UUID
`task_execution_id`	UUID
`trigger_type`	string	What started the run: `cron`, `event`, or `manual`.
`trigger_event`	string	The event that started the run; empty otherwise.
`prompt_snapshot`	string	The prompt exactly as the run used it.
`output`	string	The run’s written result.
`findings`	list of object	Issues the run recorded, each with `severity` (`critical`, `warning`, `info`), `title`, `impact`, and `action`.
`tool_calls`	list of object
`token_usage`	object
`duration_ms`	integer
`conversation_id`	UUID
`status`	string	`pending`, `running`, or `waiting` while in progress; then `completed`, `failed`, `timed_out`, `cancelled`, or `dlq` (retries used up).
`error_message`	string
`created_at`	datetime
`updated_at`	datetime

List automation packs¶

GET /automations/packs/

List automation packs, bundles of templates created together.

Response A list of objects:

Field	Type
`slug`	string
`display_name`	string
`description`	string
`category`	string
`icon`	string
`template_count`	integer

Create automations from a pack¶

POST /automations/packs/

Create every automation in a pack in one step.

Request body

Field	Type	Required
`workspace_id`	UUID	Yes
`pack_slug`	string	Yes
`display_name`	string	Yes
`shared_parameters`	object
`per_template`	object

Response

Field	Type
`id`	UUID
`pack_slug`	string
`pack_version`	string
`display_name`	string
`workspace_id`	UUID
`shared_parameters`	object
`automation_ids`	list of UUID
`created_at`	datetime
`updated_at`	datetime

List pack instances¶

GET /automations/packs/instances/

List automation packs created in the organization.

Parameters

Name	In	Type	Required
`workspace_id`	query	UUID	Yes

Response A list of objects:

Field	Type
`id`	UUID
`pack_slug`	string
`pack_version`	string
`display_name`	string
`workspace_id`	UUID
`shared_parameters`	object
`automation_ids`	list of UUID
`created_at`	datetime
`updated_at`	datetime

Get pack instance¶

GET /automations/packs/instances/{instance_id}/

Get an automation pack instance by ID.

Parameters

Name	In	Type	Required
`instance_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`pack_slug`	string
`pack_version`	string
`display_name`	string
`workspace_id`	UUID
`shared_parameters`	object
`automation_ids`	list of UUID
`created_at`	datetime
`updated_at`	datetime

Create or update a schedule¶

PUT /schedules/

Create or update a schedule for a target.

Request body

Field	Type	Required	Description
`target_type`	string	Yes	What is scheduled: `datasource` or `automation`.
`target_id`	UUID	Yes	The data source or automation ID.
`task_type`	string	Yes	`datasource.sync` or `automation.run`; one schedule per target and task type.
`cron_expression`	string	Yes	Five-field cron schedule in UTC, such as `0 6 * * *`.
`metadata`	object

Response

Field	Type
`id`	UUID
`target_type`	string
`target_id`	UUID
`task_type`	string
`cron_expression`	string
`is_active`	boolean
`last_dispatched_at`	datetime
`next_run_at`	datetime
`metadata`	object
`created_at`	datetime
`updated_at`	datetime

List schedules¶

GET /schedules/{target_type}/{target_id}

List all schedules for a target.

Parameters

Name	In	Type	Required
`target_type`	path	string	Yes
`target_id`	path	UUID	Yes

Response A list of objects:

Field	Type
`id`	UUID
`target_type`	string
`target_id`	UUID
`task_type`	string
`cron_expression`	string
`is_active`	boolean
`last_dispatched_at`	datetime
`next_run_at`	datetime
`metadata`	object
`created_at`	datetime
`updated_at`	datetime

Delete schedule¶

DELETE /schedules/{target_type}/{target_id}/{task_type}

Delete a schedule.

Parameters

Name	In	Type	Required
`target_type`	path	string	Yes
`target_id`	path	UUID	Yes
`task_type`	path	string	Yes

Response

The raw file content.

Pause schedule¶

POST /schedules/{schedule_id}/pause

Pause a schedule, keeping its configuration.

Parameters

Name	In	Type	Required
`schedule_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`target_type`	string
`target_id`	UUID
`task_type`	string
`cron_expression`	string
`is_active`	boolean
`last_dispatched_at`	datetime
`next_run_at`	datetime
`metadata`	object
`created_at`	datetime
`updated_at`	datetime

Resume schedule¶

POST /schedules/{schedule_id}/resume

Resume a paused schedule.

Parameters

Name	In	Type	Required
`schedule_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`target_type`	string
`target_id`	UUID
`task_type`	string
`cron_expression`	string
`is_active`	boolean
`last_dispatched_at`	datetime
`next_run_at`	datetime
`metadata`	object
`created_at`	datetime
`updated_at`	datetime

What’s next?¶

API overview: authentication, worked examples, and error handling
Webhooks: get events pushed to your systems instead of polling
Service accounts: create the key an integration uses