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

# Automations

> Event-driven automations that fire push notifications or show screens in response to user events.

**Automations** bind a trigger (event type) to one or more actions (push, screen). They run for users of the project, optionally narrowed by platform and segment.

## Key concepts

* **Trigger** — one or more events that cause the automation to run (e.g. `Trial Started`, `In-App Purchase`, `Refund Declined`). Events are tracked by the Qonversion SDK and referenced here by their numeric `event_id` (see the **Events** tab in the dashboard).
* **Action** — the thing the automation does: send a `push` notification, or show a `screen`. Push and screen resources are created in the Qonversion dashboard; this API references them by `uid`.
* **Platform filter** — optional, one of `iOS`, `Android`, or omitted/null for all platforms.
* **Audience (`segments`)** — optional user segment uid (created via the **Segments** tab), or `null` to run for all users.
* **Status** — `active` (firing), `inactive`, or `paused`. Toggle via `PATCH /v4/automations/{id}/status`.

## `data` shape

The `data` field is an object with a fixed schema:

```json theme={null}
{
  "platform": "iOS",
  "initiators": [
    { "uid": "2", "type": "event" }
  ],
  "actions": {
    "push":   "nCRUE7SW",
    "screen": "qUY7JXgF"
  },
  "segments": null
}
```

* `platform` — `"iOS"`, `"Android"`, or `null`.
* `initiators` — array of one or more `{uid, type}` entries. `type` is always `"event"` today; `uid` is the dashboard event id.
* `actions` — object with optional `push` and/or `screen` uids. At least one action is required. The `event` key is reserved and currently ignored.
* `segments` — segment uid (string), or `null` for all users.

On read, the response additionally includes `"type"` (derived: `"event"` when any initiator is an event).

## Available endpoints

| Method | Endpoint                              | Description                                         |
| ------ | ------------------------------------- | --------------------------------------------------- |
| GET    | `/automations`                        | List automations (cursor-paginated)                 |
| POST   | `/automations`                        | Create an automation                                |
| GET    | `/automations/{automation_id}`        | Get an automation                                   |
| PUT    | `/automations/{automation_id}`        | Replace an automation (all mutable fields required) |
| DELETE | `/automations/{automation_id}`        | Delete an automation                                |
| PATCH  | `/automations/{automation_id}/status` | Toggle `active` / `inactive` / `paused`             |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).

## Notes & limits

* **Push and event creation are dashboard-only.** The v4 API writes automations against existing push/event uids; new pushes and SDK-sent event types are not created through this API.
* **255-char** limit on `name`, **1024-char** limit on `caption`.
* `caption` on read may contain pre-rendered HTML from the dashboard (e.g. `<span>` tags highlighting key phrases); it's a display-only field.
* Pagination uses the `limit` (1–100, default 20) and `starting_after` cursor parameters.