Tasks
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/tasks | List all tasks |
| POST | /api/tasks | Create a task |
| GET | /api/tasks/tags | List all unique tags |
| GET | /api/tasks/:id | Get a single task |
| PUT | /api/tasks/:id | Update a task |
| DELETE | /api/tasks/:id | Soft-delete a task |
| POST | /api/tasks/:id/restore | Restore a deleted task |
All endpoints require authentication.
List Tasks
GET /api/tasks
Return all tasks, ordered by creation date (newest first). Includes related project and creator data.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| includeDeleted | boolean | Include soft-deleted tasks. Default: false |
| status | string or string | Filter by status: todo, in_progress, done, blocked. Pass multiple times for OR filtering |
| projectId | string | Filter by project ID |
| search | string | Search title and description (case-insensitive, partial match) |
Response: 200 OK
{
"data": [
{
"id": "abc-123",
"title": "Review PR",
"status": "todo",
"priority": 2,
"tags": ["code-review"],
"project": { "id": "proj-1", "name": "Backend", "color": "#3b82f6" },
"creator": { "id": "user-1", "name": "Tony" },
"createdAt": "2025-01-07T10:00:00.000Z"
}
]
}
Create Task
POST /api/tasks
Create a new task. The authenticated user is recorded as the creator.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | Task title (trimmed) |
| description | string | No | Task description |
| status | string | No | One of todo, in_progress, done, blocked. Default: todo |
| priority | number | No | 1 (Low), 2 (Medium), 3 (High). Default: 2 |
| projectId | string | No | Associated project ID |
| dueDate | string | No | ISO 8601 date string |
| tags | string | No | Array of tag strings. Default: [] |
Response: 200 OK
{
"data": {
"id": "abc-123",
"title": "Review PR",
"status": "todo",
"priority": 2,
"tags": [],
"project": null,
"createdAt": "2025-01-07T10:00:00.000Z"
}
}
List Tags
GET /api/tasks/tags
Return all unique tags used across non-deleted tasks, sorted alphabetically.
Response: 200 OK
{
"data": ["bug", "code-review", "feature", "urgent"]
}
Get Task
GET /api/tasks/:id
Return a single task with its related project and creator.
Response: 200 OK
{
"data": {
"id": "abc-123",
"title": "Review PR",
"status": "todo",
"priority": 2,
"project": { "id": "proj-1", "name": "Backend", "color": "#3b82f6" },
"creator": { "id": "user-1", "name": "Tony" }
}
}
Returns 404 if the task does not exist.
Update Task
PUT /api/tasks/:id
Update one or more fields on a task. Only provided fields are changed.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | No | New title |
| description | string | No | New description (set null to clear) |
| status | string | No | New status |
| priority | number | No | 1, 2, or 3 |
| projectId | string or null | No | New project ID or null to unset |
| dueDate | string or null | No | ISO date or null to clear |
| tags | string | No | Replace all tags |
When status is changed to done, the server automatically sets completedAt. When changed away from done, completedAt is cleared.
Response: 200 OK
{
"data": {
"id": "abc-123",
"title": "Review PR",
"status": "done",
"completedAt": "2025-01-07T15:30:00.000Z"
}
}
Delete Task
DELETE /api/tasks/:id
Soft-delete a task by setting deletedAt. The task is excluded from list results unless ?includeDeleted=true is passed.
Response: 200 OK
{
"data": {
"id": "abc-123",
"title": "Review PR",
"deletedAt": "2025-01-07T16:00:00.000Z"
}
}
Restore Task
POST /api/tasks/:id/restore
Restore a soft-deleted task by clearing deletedAt.
Returns 400 if the task is not currently deleted.
Response: 200 OK
{
"data": {
"id": "abc-123",
"title": "Review PR",
"deletedAt": null
}
}