Tasks

POST /api/v1/tasks

Create a new task.

Request body

{
  "title": "Fix login bug",
  "description": "Users can't log in on Safari",
  "priority": "P1",
  "teamId": "...",
  "assigneeId": "...",
  "parentId": "..."
}

Field	Type	Required	Description
title	string	✅	1–500 characters
description	string		Optional longer description
priority	P0–P3		Default: P2
teamId	UUID		Associate with a team
assigneeId	UUID		Assign to a user (must be a team member if teamId is set)
parentId	UUID		Create as a subtask (max depth: 5)

Status on creation

• No assigneeId, or assigneeId equals the creator → ACCEPTED
• assigneeId is a different user → INBOX

Response 201 — Task object.

{
  "data": {
    "id": "...",
    "title": "Fix login bug",
    "description": "Users can't log in on Safari",
    "status": "INBOX",
    "priority": "P1",
    "creatorId": "...",
    "assigneeId": "...",
    "teamId": "...",
    "parentId": null,
    "tags": [],
    "aiClassification": null,
    "depth": 0,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
}

If AI is configured, tags and aiClassification are populated asynchronously after creation.

---

Access control

A task is visible to a user when they created it, are assigned to it, or belong to the task's team.

• List and read endpoints only return visible tasks.
• Creating a subtask requires visibility on the parent task.
• Updating a task or manually classifying it requires the user to be the creator or assignee.
• Status transition endpoints require the task to be visible before transition validation.
• Deleting a task requires the user to be the creator.
• Task IDs outside the user's visibility return 404 NOT_FOUND.
• Visible tasks that the user cannot mutate return 403 FORBIDDEN.

---

GET /api/v1/tasks

List visible tasks with optional filters.

Query parameters

Parameter	Description
status	INBOX / ACCEPTED / IN_PROGRESS / DONE / REJECTED / NEEDS_CLARIFICATION
priority	P0 / P1 / P2 / P3
teamId	Filter by team
assigneeId	Filter by assignee
parentId	Filter by parent task (null for root tasks only)
limit	Page size (default: 20, max: 100)
cursor	Pagination cursor

Response 200 — Paginated list of task objects.

---

GET /api/v1/tasks/:id

Get a single visible task with its immediate visible children.

Response 200

{
  "data": {
    "id": "...",
    "title": "...",
    "children": [
      { "id": "...", "title": "Subtask 1", ... }
    ],
    ...
  }
}

---

PATCH /api/v1/tasks/:id

Update a visible task. Only the creator or assignee can update task fields.

Request body

{
  "title": "Updated title",
  "description": "Updated description",
  "priority": "P0",
  "tags": ["bug", "frontend"],
  "assigneeId": "..."
}

All fields are optional. Changing assigneeId to a different user resets the task status to INBOX.

Response 200 — Updated task object.

---

DELETE /api/v1/tasks/:id

Soft-delete a task and all its descendants. Only the creator can delete a task. Records are retained in the database with deletedAt set.

Response 200

{
  "data": { "message": "Task deleted" }
}

---

Status transitions

All transition endpoints follow the same pattern:

POST /api/v1/tasks/:id/<action>

Action	Transition	Who can call
accept	INBOX → ACCEPTED	Assignee
reject	INBOX → REJECTED	Assignee
clarify	INBOX → NEEDS_CLARIFICATION	Assignee
start	ACCEPTED → IN_PROGRESS	Assignee
done	IN_PROGRESS → DONE	Assignee
reopen	DONE → IN_PROGRESS	Assignee or Creator
resend	REJECTED → INBOX	Creator

Response 200 — Updated task object.

Errors

Code	Description
NOT_FOUND	The task does not exist or is outside the user's visibility
INVALID_TRANSITION	The current status does not allow this action
FORBIDDEN	You don't have permission to perform this action

clarify

The clarify action requires a message body:

{
  "message": "Which environment does this affect?"
}

---

POST /api/v1/tasks/:id/classify

Manually trigger AI classification for a visible task. Only the creator or assignee can classify a task. This is useful if AI was not configured when the task was created.

Response 200 — Updated task object with tags and aiClassification populated (or unchanged if no AI provider is configured).