---
title: "Create a task"
method: POST
path: "/tasks"
tags: ["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-Id` string, required

## Request body

- object
  - `title` string, required
  - `description` string
  - `projectId` string, uuid, required
  - `status` 'TODO' | 'IN_PROGRESS' | 'REVIEW' | 'DONE' | 'BLOCKED'
  - `priority` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  - `assigneeId` string, uuid, nullable
  - `dueDate` string, date-time, nullable
  - `estimatedHours` number, nullable
  - `originalDurationMinutes` integer, nullable: Planned duration in working minutes. With a startDate and no dueDate, the dueDate is derived from it
  - `remainingDurationMinutes` integer, nullable
  - `actualStart` string, date, nullable
  - `optimisticDurationMinutes` integer, nullable: Best case in working minutes; at most the duration the task is created with, or 400 OPTIMISTIC_ABOVE_DURATION
  - `pessimisticDurationMinutes` integer, nullable: Worst case in working minutes; at least the duration, or 400 PESSIMISTIC_BELOW_DURATION (PESSIMISTIC_BELOW_OPTIMISTIC when below the optimistic value)
  - `parentId` string, uuid, nullable: Parent task UUID for subtasks
  - `sprintId` string, uuid, nullable
  - `epicId` string, uuid, nullable
  - `isMilestone` boolean
  - `requesterId` string, uuid, nullable

## Response `201`

Task created

- Task
  - `id` string, uuid, required
  - `title` string, required
  - `status` 'TODO' | 'IN_PROGRESS' | 'REVIEW' | 'DONE' | 'BLOCKED', required
  - `priority` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required
  - `projectId` string, uuid, required
  - `assigneeId` string, uuid, nullable
  - `dueDate` string, date-time, nullable
  - `estimatedHours` number, nullable
  - `progress` integer, required
  - `originalDurationMinutes` integer, nullable: Planned duration in working minutes; a day is the project calendar hoursPerDay x 60 (default 480)
  - `remainingDurationMinutes` integer, nullable: Working minutes left; 0 when DONE
  - `actualStart` string, date, nullable: Day work began (YYYY-MM-DD)
  - `isManual` boolean, 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.
  - `datesFromSubtasks` boolean: 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.
  - `optimisticDurationMinutes` integer, 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
  - `pessimisticDurationMinutes` integer, nullable: Three-point estimate, worst case, in working minutes. At least the task's duration (the remaining duration once started) when written
  - `collaborators` TaskCollaborator[]: People working on the task besides its one assignee, oldest first (at most 20). Present on task reads that load them; change them with PUT /tasks/{id}/collaborators.
    - `id` string, required: User id
    - `name` string, nullable, required
    - `avatar` string, nullable, required
    - `isAgentPersona` boolean, required: An AI agent member of the organization
  - `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.
  - `assignee` object, nullable: GET /tasks/mine only, beside myRole: who holds the task
    - `id` string
    - `name` string, nullable

## Other responses

- `400`: Validation error
- `401`: Unauthorized - missing or invalid JWT
- `403`: Forbidden - insufficient role

---

[API](https://skmtc.dev/onplana/apis/onplana-api.md) · [All operations](https://skmtc.dev/onplana/apis/onplana-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onplana/apis/onplana-api/revisions/c3d6c89e9dc8?raw)