> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Tasks

> Create, assign, and update tasks in Essal Project — including subtasks, priorities, and sprint assignment.

**Tasks** are the core work unit in Essal Project. They support rich metadata — priorities, subtasks, labels, due dates, assignees — and are fully manageable via the API.

## Creating a Task

```bash theme={null}
POST /v1/project/projects/proj_01HXYZ9876/tasks
{
  "title": "Design system audit",
  "description": "Review current UI components against the new design tokens.",
  "priority": "high",
  "assignee_id": "usr_01HXYZ1111",
  "due_date": "2026-08-15",
  "labels": ["design", "frontend"],
  "sprint_id": "spr_01HXYZ_SPRINT1"
}
```

```json theme={null}
{
  "id": "task_01HXYZTASK1",
  "title": "Design system audit",
  "status": "todo",
  "priority": "high",
  "assignee": { "id": "usr_01HXYZ1111", "display_name": "Sam Chen" },
  "due_date": "2026-08-15",
  "created_at": "2026-07-10T10:30:00Z"
}
```

## Task Priorities

| Priority | Description                              |
| -------- | ---------------------------------------- |
| `urgent` | Blocker; should be worked on immediately |
| `high`   | Important; next in queue                 |
| `medium` | Default priority                         |
| `low`    | Nice to have; work when capacity allows  |
| `none`   | Unprioritised                            |

## Subtasks

Break complex tasks into subtasks to track granular progress:

```bash theme={null}
POST /v1/project/tasks/task_01HXYZTASK1/subtasks
{
  "title": "Audit typography tokens",
  "assignee_id": "usr_01HXYZ2222"
}
```

A task's `progress` field is automatically computed as the percentage of completed subtasks.

## Updating Task Status

```bash theme={null}
PATCH /v1/project/tasks/task_01HXYZTASK1
{ "status": "in_progress" }
```

Supported statuses: `todo`, `in_progress`, `in_review`, `done`, `cancelled`.

## Assigning to a Sprint

```bash theme={null}
PATCH /v1/project/tasks/task_01HXYZTASK1
{ "sprint_id": "spr_01HXYZ_SPRINT2" }
```

## Bulk Task Operations

Update or move multiple tasks at once:

```bash theme={null}
POST /v1/project/tasks/bulk-update
{
  "task_ids": ["task_01HXYZTASK1", "task_01HXYZTASK2"],
  "updates": {
    "sprint_id": "spr_01HXYZ_SPRINT2",
    "priority": "high"
  }
}
```

<Note>
  A `project.task.completed` event fires when any task transitions to `done`. Subscribe to this event to trigger downstream actions such as updating a linked Sales deal or notifying stakeholders.
</Note>