Tasks API

Read a user’s task lists. A task list is where tasks live: every mailbox comes with one called Reminders, and apps such as Apple Reminders can add more over CalDAV. Endpoints for the tasks on a list are coming next. All endpoints are under https://api.cirrux.co/public_api/v1/task_lists.

Every endpoint acts on one person’s tasks, so it needs a user-scoped OAuth token. A workspace API key is refused with 403 forbidden. Reading needs tasks.read. Tasks are granted separately from calendars: a token with calendar.read or calendar.write alone is refused with 403 insufficient_scope.

A calendar can hold events and tasks at once, which some CalDAV apps create. Such a calendar is listed here and under the Calendar API too, and a calendar that holds only tasks is listed here alone.

The task list object

Field	Type	Required	Description
object	string	no	Always `task_list`.
uuid	string	no	This list’s entry in one mailbox. The task endpoints take `task_list_uuid` instead.
task_list_uuid	string	no	The task list itself.
mailbox_uuid	string	no	The mailbox this entry belongs to.
mailbox_address	string \| null	no	That mailbox’s email address. Every mailbox has a list called "Reminders", and this tells them apart.
name	string	no	The list’s name in this mailbox.
color	string \| null	no	A `#RRGGBB` hex color.
role	string	no	Your access: `owner`, `editor` or `viewer`.
can_write	boolean	no	Whether you may change the tasks on this list (`owner` or `editor`).
source	string	no	`owned` for your own list, `shared` for one someone shared with you.
position	number \| null	no	Sort position.

Name, color and position belong to a mailbox, not to the list, so a list linked to two of your mailboxes appears twice, with the same task_list_uuid and a different uuid.

{
  "object": "task_list",
  "uuid": "6f1d2c3b-1111-4a2b-8c3d-000000000001",
  "task_list_uuid": "9a8b7c6d-2222-4e5f-9a1b-000000000002",
  "mailbox_uuid": "1c2d3e4f-3333-4a5b-8c6d-000000000003",
  "mailbox_address": "jane@example.com",
  "name": "Reminders",
  "color": "#e8985e",
  "role": "owner",
  "can_write": true,
  "source": "owned",
  "position": 1
}

Task lists

List task lists

GET/v1/task_lists

Returns every task list you can see in the token’s workspace, one entry per mailbox it is linked to, ordered by position and then name. Not paginated. Scope tasks.read.

curl https://api.cirrux.co/public_api/v1/task_lists \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/task_lists",
  "has_more": false,
  "data": [
    {
      "object": "task_list",
      "name": "Reminders",
      "task_list_uuid": "9a8b7c6d-…",
      …
    }
  ]
}