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

# Automations

> REST endpoints for scheduled standing briefs

Base path: `/api/workspaces/{workspaceId}/automations`. Ids are UUIDs. All writes require the `automations:write` scope; create, update, and delete additionally require the **Admin** role.

| Method & path                | Does                                               | Scope · role                |
| ---------------------------- | -------------------------------------------------- | --------------------------- |
| `GET /automations`           | List                                               | `automations:read`          |
| `POST /automations`          | Create                                             | `automations:write` · Admin |
| `POST /automations/parse`    | Parse a plain-English brief into automation fields | `automations:write`         |
| `GET /automations/{id}`      | Detail incl. resolved files and skills             | `automations:read`          |
| `PATCH /automations/{id}`    | Update                                             | `automations:write` · Admin |
| `DELETE /automations/{id}`   | Delete — **also deletes its spawned tasks**        | `automations:write` · Admin |
| `POST /automations/{id}/run` | Run now                                            | `automations:write`         |

## Create an automation

```json theme={null}
POST /api/workspaces/{workspaceId}/automations
{
  "name": "Weekly recap thread",
  "instructions": "Recap last week's product changes as an X thread.",
  "outputTypes": ["x"],
  "schedule": { "type": "cron", "value": "0 9 * * 1", "runLimit": 12 },
  "leadTimeMinutes": 1440,
  "requiresReview": true
}
```

* `schedule` is `{ "type": "cron", "value": "<cron expression>", "runLimit"?: n }` or `{ "type": "manual", "runLimit"?: n }`, or `null`.
* `leadTimeMinutes` (default `1440`) — how far ahead of the scheduled publish the draft task is spawned.
* `requiresReview` (default `true`) — spawned tasks go through the review queue.
* Optional context: `fileIds`, `folderIds`, `skillIds`.

Returns `201` with the bare automation object plus its computed `nextRunAt`. The `/parse` endpoint takes a plain-English description and returns these fields pre-filled — it's what the Create screen uses.

## List envelope

Listing uses **cursor pagination**, unlike tasks:

```json theme={null}
{
  "data": [ { "id": "…", "name": "…", "nextRunAt": "…", "runCount": 3, "isCompleted": false } ],
  "pagination": { "nextCursor": "…", "hasMore": true }
}
```

Pass `?cursor=` from `pagination.nextCursor` to continue (`limit` default 100, max 500).

## Run now

`POST /automations/{id}/run` spawns the task immediately and returns it with `201`. If a spawned run is already in flight you get `200` with `alreadyRunning: true` instead of a duplicate.