Tasks

Create, update, and manage tasks within your projects. Tasks support statuses, priorities, assignees, dates, tags, and story point estimates.

Endpoints

List tasks in your workspace

Scope

tasks:read

Parameters

projectIdstringFilter by project (query param)

statusstringFilter by status (see values below)

limitnumberNumber of tasks (max 100, default 50)

offsetnumberPagination offset (default 0)

Response

{
  "tasks": [
    {
      "id": "tsk_abc123",
      "taskNumber": 42,
      "identifier": "WR-42",
      "sequenceNumber": 42,
      "title": "Implement dark mode",
      "description": { "type": "doc", "content": [...] },
      "descriptionText": "Implement dark mode toggle...",
      "status": "in_progress",
      "priority": "high",
      "startDate": 1709251200000,
      "dueDate": 1709856000000,
      "completedAt": null,
      "estimatePoints": 5,
      "createdAt": "2024-03-01T00:00:00Z",
      "updatedAt": "2024-03-01T12:00:00Z",
      "author": {
        "id": "usr_abc789",
        "name": "John Doe",
        "email": "john@example.com",
        "image": "/api/media/avatars/john.jpg"
      },
      "assignee": {
        "id": "usr_def456",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "image": "/api/media/avatars/jane.jpg"
      },
      "tags": [
        { "id": "tag_abc", "name": "design", "color": "#F59E0B" },
        { "id": "tag_def", "name": "frontend", "color": "#3B82F6" }
      ],
      "project": {
        "id": "prj_xyz789",
        "name": "Product Launch",
        "color": "#3B82F6"
      }
    }
  ],
  "total": 42,
  "hasMore": true
}

Create a new task

Scope

tasks:write

Parameters

titlestringrequiredTask title (max 500 chars)

projectIdstringrequiredProject to create the task in

descriptionTextstringPlain text description

descriptionobjectRich text description (JSON)

statusstringTask status (default: todo)

prioritystringTask priority (default: none)

assigneeIdstringUser ID to assign the task to

startDatenumberStart date (Unix ms timestamp)

dueDatenumberDue date (Unix ms timestamp)

estimatePointsnumberStory point estimate

Get a single task by ID

Scope

tasks:read

Parameters

idstringrequiredTask ID (URL path)

Update an existing task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

titlestringNew title

descriptionTextstringNew plain text description

descriptionobjectNew rich text description (JSON)

statusstringNew status

prioritystringNew priority

assigneeIdstringNew assignee user ID

startDatenumberNew start date (Unix ms timestamp)

dueDatenumberNew due date (Unix ms timestamp)

estimatePointsnumberNew story point estimate

projectIdstringMove task to a different project (must be in same organization)

List comments on a task

Scope

tasks:read

Parameters

idstringrequiredTask ID (URL path)

limitnumberNumber of comments (max 100, default 50)

offsetnumberPagination offset (default 0)

Add a comment to a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

contentstringrequiredComment text (max 10,000 chars)

Edit a task comment (author only)

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

commentIdstringrequiredComment ID (URL path)

contentstringrequiredNew comment text (max 10,000 chars)

Delete a single task comment

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

commentIdstringrequiredComment ID (URL path)

Delete all comments on a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

List subtasks of a task

Scope

tasks:read

Parameters

idstringrequiredParent task ID (URL path)

Create a subtask

Scope

tasks:write

Parameters

idstringrequiredParent task ID (URL path)

titlestringrequiredSubtask title

statusstringTask status (default: todo)

prioritystringTask priority (default: none)

assigneeIdstringUser ID to assign the subtask to

List checklist items on a task

Scope

tasks:read

Parameters

idstringrequiredTask ID (URL path)

Add a checklist item to a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

textstringrequiredChecklist item text

checkedbooleanCreate the item already checked (default: false)

Update a checklist item

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

itemIdstringrequiredChecklist item ID (URL path)

textstringNew item text

checkedbooleanToggle checked state

Delete a checklist item

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

itemIdstringrequiredChecklist item ID (URL path)

Link a task to a post

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

postIdstringrequiredPost ID to link

Remove all post links from a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

List all tags on a task

Scope

tasks:read

Parameters

idstringrequiredTask ID (URL path)

Response

[
  { "id": "tag_abc", "name": "design", "color": "#F59E0B", "description": "Design work" },
  { "id": "tag_def", "name": "frontend", "color": "#3B82F6", "description": null }
]

Add a tag to a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

tagIdstringrequiredTag ID to add

Replace all tags on a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

tagIdsstring[]requiredArray of tag IDs to set

Remove a specific tag from a task

Scope

tasks:write

Parameters

idstringrequiredTask ID (URL path)

tagIdstringrequiredTag ID to remove (URL path)

Attachments

To attach a file (any type except raster images and videos, which use the Cloudflare Images/Stream flows) to a task, call POST /api/v1/media with a taskId in the request body. Up to 20 attachments per task. See the Media API reference for upload format, supported file types, and size limits.

Task Status

backlogNot yet planned.

todoPlanned and ready to be worked on. Default status for new tasks.

in_progressCurrently being worked on.

in_reviewWork complete, awaiting review.

doneCompleted and verified.

cancelledCancelled and will not be completed.

Task Priority

noneNo priority set. Default for new tasks.

lowLow priority.

mediumMedium priority.

highHigh priority.

urgentUrgent — needs immediate attention.

Dates

The startDate and dueDate fields accept Unix timestamps in milliseconds. Both fields are optional and can be set independently.

Pagination

The list tasks endpoint supports offset-based pagination. Use the offset and limit query parameters to paginate through results. The response includes a total count and hasMore flag.

Task Links

Tasks can be linked to posts using the links endpoints. This creates a bidirectional relationship between a task and a post, allowing you to reference related updates from within a task.

Task Tags

Tasks can be tagged with organization-level or project-level tags for categorization and filtering. Use POST to add individual tags, PUT to replace all tags at once, or DELETE to remove a specific tag. Tags are also included in the tags array on task responses from the list and get endpoints.

Permissions

Reading tasks requires the tasks:read scope. Creating, updating, and deleting tasks and their sub-resources requires the tasks:write scope.