Tasks

A task is one piece of work in a deliverable. Read a project’s tasks with GET /projects/:id, then change one task here. The task screens in Drum and the MCP update_task tool run the same operation, so the same rules apply everywhere.

Task dates are calendar days, written yyyy-mm-dd, in the account’s time zone.

Endpoints

To add, move or delete tasks on an opportunity, or to change their names and other fields, see Opportunities.

Change a task

PATCH /api/v1/projects/:project_id/tasks/:id changes the fields you send. Send them flat or under task. Other keys are ignored.

:project_id can be a delivery project or an opportunity. The task must be on a kept deliverable of that project.

Send at least one field.

PATCH /api/v1/projects/20488/tasks/55120
{
  "task": {
    "status": "completed",
    "due_date": "2026-10-16",
    "member_ids": [4821, 4830]
  }
}

What a change does

• Completing a task sets its completed date and records the token’s user as the member who completed it. If the account stops time entry on completed tasks, time can no longer be logged to it. Moving a task out of completed clears the completed date and who completed it.
• Deliverable progress follows its tasks, so a status change can change the deliverable’s status and progress. A status change can also run the account’s automations.
• New members must be current members of the account. Each gets an assignment with no planned hours, and Drum notifies them. On an event task the member’s booking is updated instead, and the booking notifies them.
• Removed members lose only assignments that have no planned hours, budget line, variation line or delivery data (such as logged time). Otherwise the member stays assigned and the response has an assignee_kept warning that says why.
• The budget never changes. If a member change would change the task’s budget, contract value, budget lines, variation rows or hours, the whole request is refused with 422 budget_would_change.

Send the current members with your change, so you do not remove anyone by accident. The response lists them.

Response

Returns 200:

{
  "task": {
    "id": 55120,
    "name": "Shop drawings",
    "status": "completed",
    "note": "Issue for client review before fabrication.",
    "item_type": "task",
    "start_date": "2026-10-01",
    "due_date": "2026-10-16",
    "completed_date": "2026-10-13",
    "members": [
      {"id": 4821, "name": "Jordan Reed"},
      {"id": 4830, "name": "Priya Shah"}
    ],
    "completed_by": [{"id": 4821, "name": "Jordan Reed"}],
    "deliverable": {"id": 30411, "name": "Design development"},
    "project": {"id": 20488, "name": "Riverside fit-out", "project_number": "2026-088"}
  },
  "warnings": []
}

GET /projects/:id gives task dates as timestamps. Read those in the account’s time zone: a due date of 16 October 2026 in a Sydney account is 2026-10-16T12:59:59.999Z. This endpoint gives the plain date.

Permissions

The token needs api_update. The token’s user needs one of:

• A project update permission: update_all_projects, update_team_projects (projects of their teams), or update_assigned_projects (projects or tasks they are assigned to).
• For a task on an opportunity, an opportunity update permission: update_all_opportunities, update_team_opportunities or update_assigned_opportunities.
• A task permission: manage_all_tasks, manage_team_tasks, or manage_assigned_tasks (tasks they are assigned to).

A task the token’s user can read but not change returns 403 not_authorized. A task they can neither read nor change returns 404 task_not_found.

Errors