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

# Tasks API

> Create and manage tasks with the correct visibility, dates, and assignees.

Use the tasks API to create work and keep an external system in sync. Task writes use the same underlying service as the app, including activity, notification, and integration behavior.

## Endpoints

Paths below are relative to `https://api.getkato.io/v1`.

| Method | Path         | Scope         | Result                                   |
| ------ | ------------ | ------------- | ---------------------------------------- |
| GET    | `/tasks`     | `tasks:read`  | Paginated visible tasks                  |
| GET    | `/tasks/:id` | `tasks:read`  | A visible task, including archived tasks |
| POST   | `/tasks`     | `tasks:write` | Create a task (`201`)                    |
| PATCH  | `/tasks/:id` | `tasks:write` | Update an active task                    |
| DELETE | `/tasks/:id` | `tasks:write` | Archive a task                           |

There is currently no public task-restore endpoint.

## Visibility

Owners and admins can access tasks across the workspace. A regular member's key can access tasks the member created or is assigned to. The key owner's current role is checked for every task request; scopes alone do not grant access to every task.

Inaccessible tasks return `404`. If the key owner leaves the workspace, task access stops. Parent tasks must also be accessible to the caller.

## List tasks

```bash theme={null}
curl --fail-with-body --silent --show-error --get \
  https://api.getkato.io/v1/tasks \
  -H "Authorization: Bearer $KATO_API_KEY" \
  --data-urlencode "limit=25"
```

Supported query parameters are `limit`, `cursor`, and `include_archived`. Archived tasks are excluded unless `include_archived=true`. There are no public status or assignee query filters on this endpoint; filter the returned tasks in your integration if needed.

Follow `next_cursor` while `has_more` is true. See [pagination](/api-reference/authentication#pagination).

## Create a task

```bash theme={null}
curl --fail-with-body --silent --show-error \
  https://api.getkato.io/v1/tasks \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "Prepare the Northlane kickoff",
    "description": "Confirm the agenda and collect open questions.",
    "priority": "high",
    "estimated_time": 45
  }'
```

| Input                     | Format                                              |
| ------------------------- | --------------------------------------------------- |
| `title`                   | Required string, 1–500 characters                   |
| `description`             | Optional string, up to 100,000 characters           |
| `status`                  | Workspace task-status slug                          |
| `priority`                | `no_priority`, `low`, `medium`, `high`, or `urgent` |
| `start_date` / `due_date` | Unix timestamp in milliseconds                      |
| `parent_task_id`          | Accessible parent task ID                           |
| `assignees`               | Array of workspace auth-user IDs, up to 50          |
| `estimated_time`          | Positive integer, in minutes                        |
| `linked_record_ids`       | Array of record IDs, up to 10; creation only        |

Use real workspace status slugs and auth-user IDs from your Kato workspace. The general public API does not currently provide a member directory or task-status list endpoint. You can omit optional fields for a minimal task.

## Date and response formats

Write `start_date` and `due_date` as numbers, such as the result of JavaScript's `Date.parse("2026-09-15T17:00:00Z")`. Use an explicit timezone. When both dates are set, the start must not be later than the due date.

Responses contain a mix of snake\_case and camelCase names:

| Write input      | Response property | Response format         |
| ---------------- | ----------------- | ----------------------- |
| `start_date`     | `start_date`      | ISO 8601 string or null |
| `due_date`       | `dueDate`         | ISO 8601 string or null |
| `parent_task_id` | `parent_task_id`  | Task ID or null         |
| `estimated_time` | `estimatedTime`   | Minutes or null         |

Other response properties include `id`, `title`, `description`, `status`, `priority`, `assignees`, `timeLogged`, `archived`, `createdBy`, `createdAt`, and `updatedAt`. `timeLogged` is minutes or null when unavailable. Do not send a response object straight back as an update; build the expected input fields.

## Update a task

Set `KATO_TASK_ID` to a task returned by your workspace.

```bash theme={null}
curl --fail-with-body --silent --show-error \
  -X PATCH "https://api.getkato.io/v1/tasks/$KATO_TASK_ID" \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"priority":"urgent","due_date":null}'
```

Omitted fields stay unchanged. Use `null` to clear `start_date`, `due_date`, `parent_task_id`, or `estimated_time`. Use `assignees: []` to remove all assignees. `linked_record_ids` is only accepted during creation.

## Archive a task

```bash theme={null}
curl --fail-with-body --silent --show-error \
  -X DELETE "https://api.getkato.io/v1/tasks/$KATO_TASK_ID" \
  -H "Authorization: Bearer $KATO_API_KEY"
```

This returns the task with `archived: true`. Repeating the archive operation is supported. Patching an archived task returns `404`.

Use [task webhooks](/api-reference/webhooks/events) for status and assignment changes, and [verify incoming signatures](/api-reference/webhooks/verification) before processing an event.


## Related topics

- [Developer quickstart](/api-reference/quickstart.md)
- [Create a task](/api-reference/tasks/create.md)
- [Archive a task](/api-reference/tasks/archive.md)
- [Update a task](/api-reference/tasks/update.md)
- [Get a task](/api-reference/tasks/get.md)