# Tasks API

The Tasks API manages project tasks, assignment, state transitions, notes, and dependencies. Task operations always remain inside the API Client's organization.

## Roles

| Operation | Member | Manager | Finance | HR |
|---|---:|---:|---:|---:|
| List and read tasks | Yes | Yes | Project-financial context only | Staffing context only |
| Create and update tasks | No | Yes | No | No |
| Complete a task for a member subject | No | Yes | No | No |
| Archive or restore tasks | No | Yes | No | No |

## Task object

```json
{
  "object": "task",
  "id": "tsk_01J8QA1K7M08W2DVM5RTVZJEF9",
  "project_id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC",
  "code": "DISC-10",
  "name": "Complete discovery workshop",
  "description": "Run and document the project discovery workshop.",
  "status": "in_progress",
  "priority": "high",
  "start_at": "2026-08-20T09:00:00Z",
  "due_at": "2026-08-25T17:00:00Z",
  "assignee_member_ids": ["alice@example.com"],
  "predecessor_task_ids": [],
  "custom_fields": {},
  "created_at": "2026-08-18T10:00:00Z",
  "updated_at": "2026-08-22T08:00:00Z"
}
```

## List tasks

`GET /v1/tasks`

Operation ID: `listTasks`

Filters: `project_id`, `status`, `assignee_member_id`, `priority`, `due_before`, `due_after`, `search`, `sort`, `order`, `limit`, and `after`.

## Create a task

`POST /v1/tasks`

Operation ID: `createTask`

Required Role: Manager. Required header: `Idempotency-Key`.

```json
{
  "project_id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC",
  "name": "Complete discovery workshop",
  "priority": "high",
  "due_at": "2026-08-25T17:00:00Z",
  "assignee_member_ids": ["alice@example.com"]
}
```

## Get and update a task

- `GET /v1/tasks/{task_id}` — `getTask`
- `PATCH /v1/tasks/{task_id}` — `updateTask`, Manager, `If-Match`

## Transition task state

`POST /v1/tasks/{task_id}/transitions`

Operation ID: `transitionTask`

Required Role: Manager. Required header: `Idempotency-Key`.

```json
{
  "transition": "complete",
  "completed_at": "2026-08-22T12:00:00Z",
  "subject": {
    "member_id": "alice@example.com"
  }
}
```

Supported transitions are returned with the task and may vary with its configured workflow. Supplying a subject records who the work concerns; the API Client remains actor.

## Add a note

`POST /v1/tasks/{task_id}/notes`

Operation ID: `addTaskNote`

Required Roles: Manager, or Member where the task policy permits. Required header: `Idempotency-Key`.

```json
{
  "text": "Customer confirmed the revised workshop date.",
  "subject": {
    "member_id": "alice@example.com"
  }
}
```

## Replace dependencies

`PUT /v1/tasks/{task_id}/dependencies`

Operation ID: `replaceTaskDependencies`

Required Role: Manager. Use `If-Match`. Eos rejects cross-project dependencies where the configured workflow does not allow them and rejects dependency cycles.

## Archive and restore

- `POST /v1/tasks/{task_id}/archive` — `archiveTask`
- `POST /v1/tasks/{task_id}/restore` — `restoreTask`

Both require Manager and `Idempotency-Key`.

## Common errors

`TASK_NOT_FOUND`, `PROJECT_NOT_FOUND`, `INVALID_ASSIGNEE`, `INVALID_TRANSITION`, `DEPENDENCY_CYCLE`, `STALE_RESOURCE`, and `TASK_ARCHIVE_BLOCKED`.

Next: [Time Entries API](time-entries.html).