> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

<ParamField path="orgId" type="string" required>
  Organization UUID.
</ParamField>

<ParamField path="spaceId" type="string" required>
  Space UUID.
</ParamField>

**Example**

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/tasks \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="tasks[].id" type="string">UUID of the task.</ResponseField>
<ResponseField name="tasks[].space_id" type="string">Parent space UUID.</ResponseField>
<ResponseField name="tasks[].board_id" type="string">Board this task belongs to.</ResponseField>
<ResponseField name="tasks[].column_id" type="string">Column the task is currently in.</ResponseField>
<ResponseField name="tasks[].title" type="string">Task title.</ResponseField>
<ResponseField name="tasks[].description" type="string">Optional task description.</ResponseField>
<ResponseField name="tasks[].assignee_user_id" type="string">UUID of the assigned member, or `null`.</ResponseField>
<ResponseField name="tasks[].due_at" type="string">ISO 8601 due date, or `null`.</ResponseField>
<ResponseField name="tasks[].deliverable_required" type="boolean">Whether a file deliverable is required to complete this task.</ResponseField>
<ResponseField name="tasks[].deliverable_instructions" type="string">Instructions for the deliverable, if any.</ResponseField>
<ResponseField name="tasks[].position" type="integer">Sort order within the column (ascending).</ResponseField>
<ResponseField name="tasks[].version" type="integer">Incremented on every update. Useful for optimistic concurrency.</ResponseField>

***

## 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**

<ParamField path="orgId" type="string" required>
  Organization UUID.
</ParamField>

<ParamField path="spaceId" type="string" required>
  Space UUID.
</ParamField>

**Request body**

<ParamField body="title" type="string" required>
  Task title.
</ParamField>

<ParamField body="column_id" type="string" required>
  UUID of the board column to place this task in. The column must belong to a board in this space.
</ParamField>

<ParamField body="description" type="string">
  Optional free-text description.
</ParamField>

<ParamField body="assignee_user_id" type="string">
  UUID of the organization member to assign. Must be a current member.
</ParamField>

<ParamField body="due_at" type="string">
  ISO 8601 due date/time, e.g. `"2024-04-01T00:00:00Z"`.
</ParamField>

<ParamField body="deliverable_required" type="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.
</ParamField>

<ParamField body="deliverable_instructions" type="string">
  Human-readable instructions describing what deliverable is expected.
</ParamField>

**Example**

```bash theme={null}
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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="taskId" type="string" required>Task UUID.</ParamField>

**Request body** — all fields are optional

<ParamField body="title" type="string">
  New task title.
</ParamField>

<ParamField body="description" type="string">
  New description.
</ParamField>

<ParamField body="column_id" type="string">
  Move the task to this column. The column must belong to the same space.
</ParamField>

<ParamField body="position" type="integer">
  New sort position within the column.
</ParamField>

<ParamField body="assignee_user_id" type="string">
  Reassign the task. Set to `null` to clear the assignee. Must be an organization member.
</ParamField>

<ParamField body="due_at" type="string">
  New due date. Ignored if `clear_due_at` is `true`.
</ParamField>

<ParamField body="clear_due_at" type="boolean">
  Set to `true` to remove the due date.
</ParamField>

<ParamField body="deliverable_required" type="boolean">
  Update whether a deliverable is required.
</ParamField>

<ParamField body="deliverable_instructions" type="string">
  Update deliverable instructions.
</ParamField>

**Example** — move a task to a different column

```bash theme={null}
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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="taskId" type="string" required>Task UUID.</ParamField>

**Example**

```bash theme={null}
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**

<ParamField query="org_id" type="string" required>
  Organization UUID.
</ParamField>

**Example**

```bash theme={null}
curl "https://your-hostname/api/v1/me/tasks?org_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "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**

<ParamField query="limit" type="integer">
  Maximum number of messages to return. Defaults to 50.
</ParamField>

<ParamField query="before" type="string">
  RFC3339 timestamp. Returns only messages created before this time (for pagination).
</ParamField>

**Example**

```bash theme={null}
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`

```json theme={null}
{
  "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
```

<ParamField body="content" type="string" required>
  Message text. Cannot be empty.
</ParamField>

**Example**

```bash theme={null}
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**

```bash theme={null}
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`

```json theme={null}
{
  "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.

<ParamField body="file_node_id" type="string" required>
  UUID of the file node to link. Must be a file (not a folder) under the `Deliverables` root folder of this space.
</ParamField>

**Example**

```bash theme={null}
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**

<ParamField path="fileNodeId" type="string" required>
  UUID of the file node to unlink.
</ParamField>

**Example**

```bash theme={null}
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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.