Create a task

POST /v1/tasks

Creates a new task in the team the API key is bound to. The task is auto-numbered. If taskStatusId is omitted, the team’s default status is used. Pass taskListIds to attach the task to one or more lists, parentId to make it a subtask, and description for a markdown body that the web app’s collaborative editor will render.

Connected web clients in the team receive a realtime event so the new task shows up in their UI without a refresh.

Request

No path parameters.

Body

Content-Type: application/json

Field	Type	Required	Description
title	string	yes	Task title. Must contain at least one non-whitespace character.
description	string	no	CommonMark markdown body. Headings, bold, italic, lists, code blocks, and links are preserved. Inline code, blockquotes, images, and horizontal rules are stripped.
priority	string | null	no	One of low, medium, high, urgent, or null to leave unset.
dueDate	string | null	no	ISO 8601 date string (e.g. 2026-05-12) or null.
assigneeIds	array of string	no	User IDs (UUIDs) to assign. Defaults to nobody if omitted.
taskStatusId	number	no	Numeric status ID. Falls back to the team’s default status if not provided.
parentId	number	no	If provided, the new task is created as a subtask of this parent.
taskListIds	array of number	no	Numeric IDs of lists to attach the task to. The task can be created with no lists.

Example request

{
  "title": "Wire up onboarding email",
  "description": "## Steps\n\n- Configure SMTP\n- Send via **Resend**",
  "priority": "high",
  "dueDate": "2026-05-12",
  "assigneeIds": ["u_abc123"],
  "taskListIds": [12, 19],
  "parentId": 200
}

Response

201 Created — the created task:

Field	Type	Description
id	number	Numeric ID of the new task.
title	string	Task title (trimmed).
number	number	Auto-incrementing task number within the team.
key	string	Stable UUID key for the task.
priority	string | null	The priority you sent, or null.
dueDate	string | null	The due date you sent, or null.
parentId	number | null	Parent task ID if this is a subtask, otherwise null.
createdAt	string	ISO 8601 timestamp of creation.
updatedAt	string	ISO 8601 timestamp of the last update.
status	object	The applied status — see below.
status.id	number	Numeric ID of the status.
status.name	string	Display name of the status.
assignees	array of objects	Users now assigned to the task.
assignees[].id	string	User ID (UUID).
assignees[].name	string	User’s display name.
assignees[].email	string	User’s email address.
taskLists	array of objects	Lists the task is now attached to. May be empty.
taskLists[].id	number	Numeric ID of the list.
taskLists[].name	string	Display name of the list.

400 Bad Request is returned with { "error": "..." } when:

• title is missing or empty
• One or more taskListIds don’t belong to your team
• parentId doesn’t belong to your team
• taskStatusId doesn’t belong to your team