tasks

Create a task

post/tasks

Request

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

Headers

X-Organization-Idstring required

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

Request body

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

Planned duration in working minutes. With a startDate and no dueDate, the dueDate is derived from it

remainingDurationMinutesinteger nullable
actualStartstring date nullable
optimisticDurationMinutesinteger nullable

Best case in working minutes; at most the duration the task is created with, or 400 OPTIMISTIC_ABOVE_DURATION

pessimisticDurationMinutesinteger nullable

Worst case in working minutes; at least the duration, or 400 PESSIMISTIC_BELOW_DURATION (PESSIMISTIC_BELOW_OPTIMISTIC when below the optimistic value)

parentIdstring uuid nullable

Parent task UUID for subtasks

sprintIdstring uuid nullable
epicIdstring uuid nullable
isMilestoneboolean
requesterIdstring uuid nullable

Response

Task created

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.