latestOpenAPI 3.1.02026-08-211061591.1 MB

69a962f1578f

Tasks

Create Task

Create a new task.

post/api/v1/tasks

Request body

contentstring required

Task content.

descriptionstring nullable

Task description.

project_idstring nullable

ID of the project to add the task to. If omitted or null, the task will be added to the user's Inbox.

section_idstring nullable

ID of the section to add the task to

parent_idstring nullable

ID of the parent task

orderinteger nullable

Position of the task in the project or section

labelsstring[] nullable

List of label names.

priorityinteger nullable

Task priority (1-4, where 1 is highest)

assignee_idinteger nullable

ID of the user to assign the task to. To find User IDs, use Get user for your own ID or Get all collaborators for project members.

due_stringstring nullable

Human-readable representation of the due date. See the Due dates section for more details.

due_datestring nullable

Due date in RFC 3339 format or similar. See the Due dates section for more details.

due_datetimestring nullable

Due date and time. See the Due dates section for more details.

due_langstring nullable

Due date language code. See the Due dates section for more details.

durationinteger nullable

Task duration, in either minutes or days. Only used if duration_unit is also provided.

duration_unit'minute' | 'day' nullable

Unit of time for duration.

deadline_datestring date nullable

Deadline date in YYYY-MM-DD format

Example request

{
  "content": "Buy milk",
  "description": "Pick up two liters of whole milk.",
  "project_id": "6XGgm6PHrGgMpCFX",
  "section_id": "6fFPHV272WWh3gpW",
  "parent_id": "6XGgmFVcrG5RRjVr",
  "order": 12,
  "labels": [
    "errands",
    "shopping"
  ],
  "priority": 2,
  "assignee_id": 123456789,
  "due_string": "tomorrow at 12:00",
  "due_date": "2025-02-12",
  "due_datetime": "2025-02-12T12:00:00Z",
  "due_lang": "en",
  "duration": 30,
  "duration_unit": "minute",
  "deadline_date": "2025-02-12"
}

Response

Successful Response

user_idstring required

String ID of the user who owns the task.

idstring required

String ID of the task.

project_idstring required

String ID of the project that contains the task.

section_idstring nullable required

String ID of the section that contains the task, or null if the task is not in a section.

parent_idstring nullable required

String ID of the parent task, or null if this is a top-level task.

added_by_uidstring nullable required

String ID of the user who created the task, or null if unknown.

assigned_by_uidstring nullable required

String ID of the user who assigned the task, or null if unassigned.

responsible_uidstring nullable required

String ID of the user responsible for the task, or null if unassigned.

labelsstring[] required

Names of labels attached to the task.

deadlineobject nullable required

Deadline details for the task, or null when the task has no deadline.

durationobject nullable required

Task duration details, or null when the task has no duration.

is_collapsedboolean required

Whether the task is collapsed in the user's view.

checkedboolean required

Whether the task is completed.

is_deletedboolean required

Whether the task is deleted.

added_atstring date-time nullable required

Date and time when the task was created, or null if unknown.

completed_atstring date-time nullable required

Date and time when the task was completed, or null if active.

completed_by_uidstring nullable required

String ID of the user who completed the task, or null if active.

updated_atstring date-time nullable required

Date and time when the task was last updated, or null if unknown.

dueobject nullable required

Due date details for the task, or null when the task has no due date.

priorityinteger required

Task priority from 1 (normal) to 4 (urgent).

child_orderinteger required

Position of the task among sibling tasks.

order_keystring nullable required

Fractional-indexing order key: tasks sort by comparing keys lexicographically among siblings sharing the same project, section and parent task. May be null for tasks not yet migrated.

contentstring required

Task content.

descriptionstring required

Task description.

note_countinteger required

Deprecated: only returns 0 and is marked for removal.

day_orderinteger required

Task order for day-based views.

completed_countinteger required

Number of times the task has been marked as completed. Increments on every completion, including recurring occurrences and re-completions of a previously reopened task. Decremented when a recurring completion is undone.

postponed_countinteger required

Number of times the task's due date has been rescheduled by the user. Increments on any due-date change between two set dates (forward or backward); recurring completions and undos are not counted.

Example response

{
  "user_id": "1234567",
  "id": "6XGgmFVcrG5RRjVr",
  "project_id": "6XGgm6PHrGgMpCFX",
  "section_id": "6fFPHV272WWh3gpW",
  "parent_id": "6XGgmFVcrG5RRjVr",
  "added_by_uid": "1234567",
  "assigned_by_uid": "1234567",
  "responsible_uid": "1234567",
  "labels": [
    "priority"
  ],
  "deadline": {
    "date": "2025-02-12",
    "lang": "en"
  },
  "duration": {
    "amount": 30,
    "unit": "minute"
  },
  "added_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-16T10:30:00Z",
  "completed_by_uid": "1234567",
  "updated_at": "2025-01-17T10:30:00Z",
  "due": {
    "date": "2025-02-12",
    "is_recurring": false,
    "lang": "en",
    "string": "tomorrow"
  },
  "priority": 1,
  "child_order": 1,
  "order_key": "a1V",
  "content": "Buy milk",
  "description": "Pick up organic milk",
  "day_order": 1,
  "completed_count": 3,
  "postponed_count": 1
}