# /containers

8 routes.

## GET /v1/containers

List containers

**Scopes** — `containers:read`

**Query**

| parameter | type | | limit |
|---|---|---|---|
| `limit` | integer | optional | max 200 |
| `cursor` | string | optional | max 4096 chars |
| `updated_since` | string | optional | max 24 chars |
| `kind` | `area` · `project` · `subproject` | optional | — |
| `parent_id` | string | optional | max 64 chars |
| `status` | `active` · `archived` | optional | — |

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

## POST /v1/containers

Create a container

**Scopes** — `containers:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `kind` | `area` · `project` · `subproject` | required | — |
| `name` | string | required | max 256 chars, min 1 |
| `parentId` | string | optional | max 64 chars, — |
| `subtitle` | string | optional | max 512 chars, — |
| `notes` | string | optional | max 100000 chars, — |
| `symbol` | string | optional | max 64 chars, — |
| `colorHex` | string | optional | max 16 chars, — |
| `deadline` | string | optional | max 10 chars, — |
| `priority` | `low` · `medium` · `high` | optional | —, — |
| `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/containers/{id}

One container

**Scopes** — `containers:read`

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

## PATCH /v1/containers/{id}

Change a container (not parentId/kind — use /move)

**Scopes** — `containers:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `name` | string | optional | max 256 chars, min 1 |
| `subtitle` | string | optional | max 512 chars, — |
| `notes` | string | optional | max 100000 chars, — |
| `symbol` | string | optional | max 64 chars, — |
| `colorHex` | string | optional | max 16 chars, — |
| `deadline` | string | optional | max 10 chars, — |
| `priority` | `low` · `medium` · `high` | optional | —, — |
| `status` | `active` · `archived` | optional | — |

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

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

Re-parent and reorder

**Scopes** — `containers:write`

**Request body**

| field | type | | limit |
|---|---|---|---|
| `parentId` | string | required | max 64 chars, — |
| `kind` | `area` · `project` · `subproject` | optional | — |
| `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/containers/{id}/trash

Trash a container

**Scopes** — `containers:write`

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

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

Restore a container

**Scopes** — `containers:write`

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

## DELETE /v1/containers/{id}

Delete permanently (cascades)

**Scopes** — `containers:write`

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