tasks

Update a task

Needs task.edit.any, or task.edit.own on a task the caller holds or collaborates on. A caller whose only right is collaborating cannot change assigneeId (403 COLLABORATOR_FIELD_REFUSED); collaborators themselves change through PUT /tasks/{id}/collaborators. Assigning the task to one of its collaborators takes them off the collaborator list.

put/tasks/{id}

Request

  • Base URL: https://api.onplana.com/api
  • URL: https://api.onplana.com/api/tasks/{id}
  • Auth: one of:
    • HTTP bearer
    • API key in header Authorization

Path parameters

idstring required

Task UUID

Headers

X-Organization-Idstring required

UUID of the active organization. Sets org context for all scoped operations.

Request body

titlestring
descriptionstring
status'TODO' | 'IN_PROGRESS' | 'REVIEW' | 'DONE' | 'BLOCKED'
priority'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
assigneeIdstring nullable
dueDatestring date-time nullable
estimatedHoursnumber nullable
progressinteger
originalDurationMinutesinteger nullable

Planned duration in working minutes. Setting it on a task with a startDate moves the dueDate; sending dates too lets the dates win

remainingDurationMinutesinteger nullable

Working minutes left; defaults to original x (1 - progress); DONE forces 0

actualStartstring date nullable

Stamped from startDate the first time the task leaves TODO or gains progress; settable

optimisticDurationMinutesinteger nullable

Best case in working minutes, null to clear. Checked only when sent: at most the duration the task has after this write (the remaining duration once started)

pessimisticDurationMinutesinteger nullable

Worst case in working minutes, null to clear. Checked only when sent: at least the duration after this write, and at least the optimistic value

sprintIdstring nullable
epicIdstring nullable

Response

Updated task

idstring uuid required
titlestring required
status'TODO' | 'IN_PROGRESS' | 'REVIEW' | 'DONE' | 'BLOCKED' required
priority'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' required
projectIdstring uuid required
assigneeIdstring uuid nullable
dueDatestring date-time nullable
estimatedHoursnumber nullable
progressinteger required
originalDurationMinutesinteger nullable

Planned duration in working minutes; a day is the project calendar hoursPerDay x 60 (default 480)

remainingDurationMinutesinteger nullable

Working minutes left; 0 when DONE

actualStartstring date nullable

Day work began (YYYY-MM-DD)

isManualboolean nullable

For a task with subtasks: true keeps its own dates, false takes its start and due dates from its subtasks, null follows the project's parentDatesFromSubtasks. Read only while the server switch parent_date_rollup_enabled is on.

datesFromSubtasksboolean

True when this task's start and due dates come from its subtasks right now (it has subtasks, is not a milestone or held by a live Planner sync, and its isManual or its project's default says so); a change to its dates, durations or constraint is then refused with PARENT_DATES_FROM_SUBTASKS. False whenever the server switch parent_date_rollup_enabled is off. On GET /tasks, /tasks/mine, /tasks/delegated-to-agents and /projects/{id}/tasks; the same flag the MCP task tools return.

optimisticDurationMinutesinteger nullable

Three-point estimate, best case, in working minutes. At most the task's duration (the remaining duration once started) when written; used by schedule risk runs. Null: the run's default range applies

pessimisticDurationMinutesinteger nullable

Three-point estimate, worst case, in working minutes. At least the task's duration (the remaining duration once started) when written

myRole'collaborator'

GET /tasks/mine only: present on a row the caller collaborates on but does not hold. Such a row also carries assignee; a row the caller holds carries neither.

Changes

No recorded changes to this operation across all 1 revision of this API.