Skip to main content
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 & pathDoesScope · role
GET /automationsListautomations:read
POST /automationsCreateautomations:write · Admin
POST /automations/parseParse a plain-English brief into automation fieldsautomations:write
GET /automations/{id}Detail incl. resolved files and skillsautomations:read
PATCH /automations/{id}Updateautomations:write · Admin
DELETE /automations/{id}Delete — also deletes its spawned tasksautomations:write · Admin
POST /automations/{id}/runRun nowautomations: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.