---
method: PUT
path: /api/collections/:id
auth: jwt
area: collections
---
<!-- source: internal/handlers/collections.go:399 CollectionHandler.UpdateCollection -->

# Update Collection

Updates name/metadata, replaces the rule set, and merges view settings.
Note the quirk: **the success status is 201**, not 200 (historical).

The playlist toggles `hide_finished` / `show_up_next` are accepted as
top-level single-element arrays (an htmx form artifact — the LAST value wins)
and are merged into `view_settings` server-side. JSON clients may prefer to
set `view_settings.hide_finished` / `view_settings.show_up_next` directly.

## Example request

```json example-request
{
  "name": "To Read (2026)",
  "description": "Updated description",
  "color": "#33CCFF",
  "icon": "📚",
  "auto_assign_rules": [],
  "view_settings": { "hide_finished": true },
  "hide_finished": ["true"],
  "show_up_next": ["true"]
}
```

## Example response

```json example-response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "8f14e45f-ceea-467f-a429-0b21bfc0b1a2",
  "name": "To Read (2026)",
  "description": "Updated description",
  "color": "#33CCFF",
  "icon": "📚",
  "auto_assign_rules": null,
  "view_settings": { "hide_finished": true, "show_up_next": true },
  "created_at": "2026-10-24 13:57:01.81234 +0000 UTC"
}
```

`created_at` uses Go's `time.String()` format, not RFC3339.

## Request fields

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| name | string | yes | |
| description | string | no | |
| color | string | no | |
| icon | string | no | |
| auto_assign_rules | array | no | replaces the whole rule set (rule object shape: see Create Collection) |
| view_settings | object | no | merged into stored settings |
| hide_finished | array | no | single-element string array `["true"]`/`["false"]`; merged into view_settings |
| show_up_next | array | no | same shape as `hide_finished` |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid collection id"}` / `{"error": "invalid request"}` | malformed id or body |
| 500 | `{"error": "..."}` | unexpected server error |