Tasks

List a project's tasks

GET /api/v1/projects/{id}/tasks

Any role that can see the project. Returns all of the project's tasks, newest first, each with its assignee ({ id, name } or null).

{
  "tasks": [
    {
      "id": "cm9...",
      "title": "Set up staging environment",
      "description": null,
      "status": "IN_PROGRESS",
      "estimatedHours": "6",
      "dueDate": "2026-08-14T00:00:00.000Z",
      "projectId": "cm9...",
      "assigneeId": "cm9...",
      "assignee": { "id": "cm9...", "name": "Dana Ruiz" },
      "createdAt": "2026-08-03T09:15:00.000Z",
      "...": "..."
    }
  ]
}

Errors: 404 "Project not found." if the project doesn't exist, is in another organization, or is confidential and the key's owner isn't on it.

Create a task

POST /api/v1/projects/{id}/tasks

Any role that can see the project. Returns 201 with { "task": { ... } }.

titlestringrequired

Up to 200 characters.

descriptionstring

Up to 2,000 characters.

assigneeIdstring

A user ID to assign the task to (see the MCP list_members tool for IDs). They must be in the organization and able to see the project (on a confidential project: on its team, or an owner or admin). The assignee is notified in the app unless they're the key's owner. If you leave it out and the organization has only one person, the task is assigned to them.

estimatedHoursnumber

Greater than zero.

dueDatestring | null

A day, YYYY-MM-DD (for example 2026-08-14). The assignee is reminded the day before and if it passes (see Calendar). It comes back as midnight UTC on that day.

If the project is linked to Linear, the task is also created there.

curl -X POST https://<your-instance>/api/v1/projects/cm9.../tasks \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Set up staging environment"}'

Errors: 404 "Project not found."; 422 with field errors such as { "error": { "title": ["Title is required"] } } or { "error": { "dueDate": ["Use a date like 2026-07-23 (YYYY-MM-DD)."] } } (also "That date doesn't exist." for, say, 2026-02-30); 422 "That person can't be assigned tasks on this project." for an assigneeId who can't see the project.

Update a task

PATCH /api/v1/tasks/{id}

Any role that can see the task's project. Send only the fields you want to change. Returns { "task": { ... } }. A change is pushed to the linked Linear issue, if any.

statusstring

TODO, IN_PROGRESS, or DONE.

assigneeIdstring | null

A user ID, or null to unassign. Same rule as when creating: they must be able to see the project. A new assignee is notified in the app unless they're the key's owner.

dueDatestring | null

YYYY-MM-DD, or null to clear it. A new date re-arms the due-date reminders.

To change a task's title, description or estimate, use the app or the MCP update_task tool.

Errors: 404 "Task not found." if the task doesn't exist, is in another organization, or is on a confidential project the key's owner isn't on; 422 "Invalid status."; 422 "Invalid assigneeId." (not a string or null); 422 { "error": { "dueDate": [...] } } for a due date that isn't YYYY-MM-DD or doesn't exist; 422 "That person can't be assigned tasks on this project.".

Delete a task

DELETE /api/v1/tasks/{id}

Any role that can see the task's project. Returns { "ok": true }. Deleting a task also deletes its comments; time logged against it stays on the project.

Errors: 404 "Task not found." (also for a task on a confidential project the key's owner isn't on).

List a task's comments

GET /api/v1/tasks/{id}/comments

Any role that can see the task's project. Returns { "comments": [ ... ] }, oldest first. Each comment has:

Field	Description
`id`	Comment ID.
`body`	The text. Mentions look like `@[Name](user:USER_ID)`.
`createdAt`	ISO timestamp.
`author`	`{ id, name }`, or `null` for comments pulled in from Linear or whose author's account was deleted.
`authorName`	The author's name, including a Linear user's name for comments from Linear.
`source`	`app`, or `linear` for comments pulled in from the task's Linear issue.
`sharedWithClient`	Whether the comment shows on the project's client link.
`linearUrl`	The comment's URL on the Linear issue, when it's there too; otherwise `null`.

Errors: 404 "Task not found.".

Comment on a task

POST /api/v1/tasks/{id}/comments

Any role that can see the task's project. Returns 201 with { "comment": { ... } } in the shape above.

bodystringrequired

Up to 5,000 characters. Notifies the task's assignee and watchers. Mention someone with @[Name](user:USER_ID) to notify them directly (and make them a watcher); mentions of people who can't see the project are ignored.

shareWithClientbooleandefault: false

Show the comment on the project's client link. It only appears there while the project's share link shows tasks.

postToLinearbooleandefault: true

On a task linked to a Linear issue, also post the comment there. Ignored for unlinked tasks.

curl -X POST https://<your-instance>/api/v1/tasks/cm9.../comments \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body": "Staging is ready for review.", "postToLinear": false}'

Errors: 404 "Task not found."; 422 with field errors such as { "error": { "body": ["Write something first"] } }.

Delete a comment

DELETE /api/v1/tasks/{id}/comments/{commentId}

Returns { "ok": true }. Authors can delete their own comments; owners and admins can delete any. A copy already posted to Linear stays there.

Errors: 404 "Comment not found."; 403 "Only the author or an admin can delete this comment.".