> ## 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.

# Tasks

> REST endpoints for the review-gate loop

Base path: `/api/workspaces/{workspaceId}/tasks`. Ids are UUIDs.

| Method & path                   | Does                                   | Scope · role             |
| ------------------------------- | -------------------------------------- | ------------------------ |
| `POST /tasks`                   | Create a task                          | `tasks:write`            |
| `GET /tasks`                    | List tasks                             | `tasks:read`             |
| `GET /tasks/review`             | Next task awaiting review              | `tasks:read`             |
| `GET /tasks/{taskId}`           | Full detail incl. content and comments | `tasks:read`             |
| `PATCH /tasks/{taskId}`         | Update a task                          | `tasks:write` · Admin    |
| `DELETE /tasks/{taskId}`        | Soft-delete                            | `tasks:write` · Admin    |
| `POST /tasks/{taskId}/approve`  | Approve a reviewed draft               | `tasks:write` · Reviewer |
| `POST /tasks/{taskId}/reject`   | Reject with optional comment           | `tasks:write` · Reviewer |
| `POST /tasks/{taskId}/publish`  | Publish an approved task               | `tasks:write` · Reviewer |
| `POST /tasks/{taskId}/retry`    | Re-run a failed task                   | `tasks:write` · Admin    |
| `GET /tasks/{taskId}/comments`  | List comments                          | `tasks:read`             |
| `POST /tasks/{taskId}/comments` | Add a comment                          | `tasks:write`            |

## Create a task

```json theme={null}
POST /api/workspaces/{workspaceId}/tasks
{
  "title": "Post about the v2.0 launch",
  "instructions": "Write an upbeat announcement for developers.",
  "outputTypes": ["x", "linkedin"],
  "publishMode": "manual",
  "requiresReview": true,
  "skillIds": [],
  "fileIds": []
}
```

`title` is the only required field. `publishMode` is `"immediate" | "scheduled" | "manual"` (default `"manual"`); `"scheduled"` additionally requires `publishAt` (ISO timestamp). `requiresReview` defaults to `true` and is **forced true for Viewer-role callers**. Returns `201` with the bare task object.

## List tasks

```
GET /tasks?status=review&limit=50&offset=0
```

Returns a bare JSON array (offset pagination, `limit` 1–100). Each task includes its `contentItems` and an `isOverdue` flag. The `status` filter accepts `todo`, `working`, `review`, `approved`, `published`, `deleted`, `failed`. A task's status field can additionally be `publishing` while a publish is in flight (not filterable).

## Approve, reject, publish

**Approve** requires the task to be in `review`. The response includes `willPublishAt` — `"immediately"`, `"manual"`, or the scheduled timestamp — telling you what happens next.

**Reject** accepts an optional `{ "comment": "…" }`, returns the task to `todo`, bumps `revisionCount`, and keeps the assignee — the same worker revises. Rejecting an `approved` task also clears the approval (the "revise" flow).

**Publish** publishes an `approved` task now — the manual-mode trigger.