---
method: GET
path: /api/collections/:id
auth: jwt
area: collections
---
<!-- source: internal/handlers/collections.go:243 CollectionHandler.GetCollection -->

# Get Collection

Returns one collection with its books and, for smart collections, the
computed Up Next entries.

## Example request

```text
GET /api/collections/550e8400-e29b-41d4-a716-446655440000
```

## Example response

```json example-response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "8f14e45f-ceea-467f-a429-0b21bfc0b1a2",
  "name": "To Read",
  "description": "Books I want to read soon",
  "color": "#00FF00",
  "icon": "📖",
  "auto_assign_rules": null,
  "view_settings": { "kobo": { "view_mode": "grid" } },
  "books": [],
  "book_count": 0,
  "is_smart": false,
  "up_next": [],
  "created_at": "2026-10-24 13:57:01.81234 +0000 UTC"
}
```

`created_at` uses Go's `time.String()` format, not RFC3339. `books` and
`up_next` are book-card arrays; `up_next` items carry
`id`, `title`, `author`, `cover`, `format`, `progress`.

## Query parameters

| Param | Type | Notes |
| ----- | ---- | ----- |
| library_id | uuid | optional; scopes items/counts to one library (invalid values are rejected with 400) |

## Response fields

| Field | Type | Notes |
| ----- | ---- | ----- |
| id | string (uuid) | |
| user_id | string (uuid) | owner |
| name | string | |
| description | string | |
| color | string | |
| icon | string | |
| auto_assign_rules | array \| null | |
| view_settings | object | |
| books | array | book cards in this collection |
| book_count | number | length of `books` |
| is_smart | boolean | |
| up_next | array | smart collections only: computed next-up entries |
| created_at | string | |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid collection id"}` / `{"error": "invalid library_id"}` | malformed id(s) |
| 404 | `{"error": "collection not found"}` | no such collection |
| 500 | `{"error": "..."}` | unexpected server error |