---
title: "Parse natural language into a structured task (ALL PLANS - aiCore)"
method: POST
path: "/ai/tasks/parse"
tags: ["ai"]
---

# Parse natural language into a structured task (ALL PLANS - aiCore)

`POST /ai/tasks/parse`

## Request

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

Extracts title, description, priority, dueDate, and assignee hints from free text.

## Headers

- `X-Organization-Id` string, required

## Request body

- object
  - `text` string, required: Free-text task description, e.g. "Remind John to review the API design doc by Friday"

## Response `200`

Parsed task fields

- 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
- `402`: Plan gate - feature not available on current plan

---

[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)