Tasks

Create, read, update, and delete board tasks. Manage messages and file deliverables attached to tasks.

Tasks live on a board column within a space. Each task can have an assignee, a due date, messages, and linked file deliverables.

List tasks

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks

Returns all tasks in a space, ordered by column and position.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Example

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "tasks": [
    {
      "id": "018e1234-abcd-7000-8000-000000000030",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "board_id": "018e1234-abcd-7000-8000-000000000010",
      "column_id": "018e1234-abcd-7000-8000-000000000020",
      "title": "Write API docs",
      "description": "Document all REST endpoints",
      "assignee_user_id": "018e1234-abcd-7000-8000-000000000050",
      "due_at": "2024-04-01T00:00:00Z",
      "deliverable_required": true,
      "deliverable_instructions": "Upload a PDF to the Deliverables folder",
      "position": 1,
      "version": 3,
      "created_at": "2024-03-15T10:00:00Z",
      "updated_at": "2024-03-20T14:30:00Z"
    }
  ]
}

tasks[].id · string

UUID of the task.

tasks[].space_id · string

Parent space UUID.

tasks[].board_id · string

Board this task belongs to.

tasks[].column_id · string

Column the task is currently in.

tasks[].title · string

Task title.

tasks[].description · string

Optional task description.

tasks[].assignee_user_id · string

UUID of the assigned member, or null.

tasks[].due_at · string

ISO 8601 due date, or null.

tasks[].deliverable_required · boolean

Whether a file deliverable is required to complete this task.

tasks[].deliverable_instructions · string

Instructions for the deliverable, if any.

tasks[].position · integer

Sort order within the column (ascending).

tasks[].version · integer

Incremented on every update. Useful for optimistic concurrency.

---

Create a task

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks

Creates a new task at the bottom of the specified column. Requires the tasks.write permission.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Request body

title · string · required

Task title.

column_id · string · required

UUID of the board column to place this task in. The column must belong to a board in this space.

description · string

Optional free-text description.

assignee_user_id · string

UUID of the organization member to assign. Must be a current member.

due_at · string

ISO 8601 due date/time, e.g. "2024-04-01T00:00:00Z".

deliverable_required · boolean

If true, a file deliverable must be linked before the task is considered complete. A Deliverables folder is created automatically in the space’s file tree if it does not exist.

deliverable_instructions · string

Human-readable instructions describing what deliverable is expected.

Example

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Write API docs",
    "column_id": "018e1234-abcd-7000-8000-000000000020",
    "assignee_user_id": "018e1234-abcd-7000-8000-000000000050",
    "due_at": "2024-04-01T00:00:00Z",
    "deliverable_required": true,
    "deliverable_instructions": "Upload a PDF to the Deliverables folder"
  }'

Response 201 Created

Returns the created task object (same shape as the list item).

---

Update a task

PATCH /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}

Partially updates a task. Only fields present in the request body are changed.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

taskId · string · required

Task UUID.

Request body — all fields are optional

title · string

New task title.

description · string

New description.

column_id · string

Move the task to this column. The column must belong to the same space.

position · integer

New sort position within the column.

assignee_user_id · string

Reassign the task. Set to null to clear the assignee. Must be an organization member.

due_at · string

New due date. Ignored if clear_due_at is true.

clear_due_at · boolean

Set to true to remove the due date.

deliverable_required · boolean

Update whether a deliverable is required.

deliverable_instructions · string

Update deliverable instructions.

Example — move a task to a different column

curl -X PATCH \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"column_id": "018e1234-abcd-7000-8000-000000000021", "position": 1}'

Response 200 OK

Returns the updated task object.

---

Delete a task

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}

Permanently deletes a task. Requires the tasks.write permission.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

taskId · string · required

Task UUID.

Example

curl -X DELETE \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content

---

List my assigned tasks

GET /api/v1/me/tasks?org_id={orgId}

Returns up to 200 tasks assigned to the authenticated user in the given organization, ordered by most recently updated. Only tasks in spaces the user has access to are returned.

Query parameters

org_id · string · required

Organization UUID.

Example

curl "https://your-hostname/api/v1/me/tasks?org_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "tasks": [
    {
      "id": "018e1234-abcd-7000-8000-000000000030",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "board_id": "018e1234-abcd-7000-8000-000000000010",
      "column_id": "018e1234-abcd-7000-8000-000000000020",
      "title": "Write API docs",
      "description": "",
      "organization_id": "018e1234-abcd-7000-8000-000000000000",
      "space_name": "Engineering",
      "position": 1,
      "version": 1,
      "created_at": "2024-03-15T10:00:00Z",
      "updated_at": "2024-03-15T10:00:00Z"
    }
  ]
}

Each item includes organization_id and space_name in addition to the standard task fields.

---

Task messages

List messages

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}/messages

Returns messages on a task thread in chronological order.

Query parameters

limit · integer

Maximum number of messages to return. Defaults to 50.

before · string

RFC3339 timestamp. Returns only messages created before this time (for pagination).

Example

curl "https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID/messages?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "messages": [
    {
      "id": "018e1234-abcd-7000-8000-000000000060",
      "task_id": "018e1234-abcd-7000-8000-000000000030",
      "author_user_id": "018e1234-abcd-7000-8000-000000000050",
      "content": "Starting on this now.",
      "created_at": "2024-03-16T08:00:00Z"
    }
  ]
}

Post a message

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}/messages

content · string · required

Message text. Cannot be empty.

Example

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Draft is ready for review."}'

Response 201 Created

Returns the created message object.

---

Deliverables

Deliverables are files from the space’s Deliverables folder that are explicitly linked to a task as evidence of completion.

List deliverables

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}/deliverables

Example

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID/deliverables \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "deliverables": [
    {
      "task_id": "018e1234-abcd-7000-8000-000000000030",
      "file_node_id": "018e1234-abcd-7000-8000-000000000070",
      "added_by": "018e1234-abcd-7000-8000-000000000050",
      "created_at": "2024-03-22T12:00:00Z",
      "file_name": "api-docs-draft.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 204800
    }
  ]
}

Link a deliverable

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}/deliverables

Links an existing file node to a task as a deliverable. The file must already exist under the space’s Deliverables folder in the file tree.

file_node_id · string · required

UUID of the file node to link. Must be a file (not a folder) under the Deliverables root folder of this space.

Example

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID/deliverables \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_node_id": "018e1234-abcd-7000-8000-000000000070"}'

Response 204 No Content

Unlink a deliverable

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/tasks/{taskId}/deliverables/{fileNodeId}

Removes the link between a file and a task. Does not delete the file itself.

Path parameters

fileNodeId · string · required

UUID of the file node to unlink.

Example

curl -X DELETE \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks/YOUR_TASK_ID/deliverables/YOUR_FILE_NODE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content