> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Automations

> Understand dashboard-managed Automations and their API execution model.

An Automation is a dashboard-managed definition that specifies its agent, wait steps, calling behavior, retry rules, branching, and downstream actions. The REST API lists summaries and creates Automation runs; it does not redefine those behaviors in a request.

## Select an active Automation

`GET /automations?status=active` returns organization-visible summaries with `id`, `name`, `description`, `status`, and `input_fields`. Use the returned `id` as `automation_id`. The catalog is read-only through this API.

## Understand input declarations

In the current API version, `input_fields` is empty:

```json theme={null}
{
  "id": "atm_demo_001",
  "name": "Renewal follow-up",
  "description": "Calls one contact and records the outcome.",
  "status": "active",
  "input_fields": []
}
```

When `input_fields` is empty, omit `input` from `POST /automation-runs` or send `{}` only. Do not send undeclared names.

## Start a run

`POST /automation-runs` accepts one active `automation_id` and one existing or inline contact reference. It does not accept an agent override, timing override, retry rule, or branch choice. The response is an asynchronous Automation run API resource.

Only if a later API response returns a nonempty `input_fields` declaration may a client send exactly those named fields. The declaration returned by the API is authoritative.

## Track and cancel

Retrieve the run until `status` is terminal. A second active run for the same Automation and contact can return `409 duplicate_active_run` with the existing run ID in safe details.

Cancellation prevents queued work from starting or marks a nonterminal run cancelled between step boundaries. It does not interrupt a step already executing, and external effects remain best-effort. See [Status lifecycles](/en/concepts/status-lifecycle) for every API-visible state.