Automations - Automate It

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

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:

{
  "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.