# /todos

12 routes.

## GET /v1/todos

List to-dos

**Scopes** — `todos:read`

**Query**

| parameter | type | | limit |
|---|---|---|---|
| `limit` | integer | optional | max 200 |
| `cursor` | string | optional | max 4096 chars |
| `updated_since` | string | optional | max 24 chars |
| `parent_id` | string | optional | max 64 chars |
| `status` | `open` · `someday` · `done` | optional | — |
| `tag` | string or array of string | optional | max 64 chars, min 1, — |
| `when_from` | string | optional | max 10 chars |
| `when_to` | string | optional | max 10 chars |
| `deadline_from` | string | optional | max 10 chars |
| `deadline_to` | string | optional | max 10 chars |
| `include_trashed` | `true` · `false` | optional | — |

**Errors** — [account_too_large](/errors/account_too_large) · [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos

Create a to-do (unknown tags are created)

**Scopes** — `todos:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `title` | string | required | max 512 chars, min 1 |
| `parentId` | string | optional | max 64 chars, — |
| `subtitle` | string | optional | max 512 chars, — |
| `notes` | string | optional | max 100000 chars, — |
| `tags` | array of string | optional | max 64 items |
| `whenDate` | string | optional | max 10 chars, — |
| `deadline` | string | optional | max 10 chars, — |
| `status` | `open` · `someday` · `done` | optional | — |
| `priority` | `low` · `medium` · `high` | optional | —, — |
| `colorHex` | string | optional | max 16 chars, — |
| `colorStyle` | string | optional | max 8 chars, — |
| `reminderTime` | string | optional | max 16 chars, — |
| `recurrenceRule` | string | optional | max 512 chars, — |
| `id` | string | optional | max 64 chars |

**Errors** — [validation_failed](/errors/validation_failed) · [duplicate_id](/errors/duplicate_id) · [conflict](/errors/conflict) · [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## GET /v1/todos/{id}

One to-do

**Scopes** — `todos:read`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## PATCH /v1/todos/{id}

Change a to-do (not parentId/status — use the actions)

**Scopes** — `todos:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `title` | string | optional | max 512 chars, min 1 |
| `subtitle` | string | optional | max 512 chars, — |
| `notes` | string | optional | max 100000 chars, — |
| `tags` | array of string | optional | max 64 items, — |
| `whenDate` | string | optional | max 10 chars, — |
| `deadline` | string | optional | max 10 chars, — |
| `priority` | `low` · `medium` · `high` | optional | —, — |
| `colorHex` | string | optional | max 16 chars, — |
| `colorStyle` | string | optional | max 8 chars, — |
| `reminderTime` | string | optional | max 16 chars, — |
| `recurrenceRule` | string | optional | max 512 chars, — |

**Errors** — [validation_failed](/errors/validation_failed) · [duplicate_id](/errors/duplicate_id) · [conflict](/errors/conflict) · [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/complete

Complete (spawns the next occurrence when recurring)

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/uncomplete

Un-complete

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/someday

Park

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/anytime

Detach and unschedule

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/move

Re-parent and reorder

**Scopes** — `todos:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `parentId` | string | required | max 64 chars, — |
| `after` | string | optional | max 64 chars |
| `before` | string | optional | max 64 chars |

**Errors** — [validation_failed](/errors/validation_failed) · [duplicate_id](/errors/duplicate_id) · [conflict](/errors/conflict) · [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/trash

Trash a to-do

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## POST /v1/todos/{id}/restore

Restore a to-do

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)

## DELETE /v1/todos/{id}

Delete permanently

**Scopes** — `todos:write`

**Errors** — [unauthorized](/errors/unauthorized) · [rate_limited](/errors/rate_limited)