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

# List Collections

Lists the signed-in user's collections with live book counts. Smart
(rule-driven) collections are **excluded by default** so legacy readers never
see stale membership — pass `include_auto=true` to include them.

## Example request

```text
GET /api/collections?include_auto=true&sort_by=name
```

## Example response

```json example-response
{
  "collections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "To Read",
      "description": "Books I want to read soon",
      "color": "#00FF00",
      "icon": "📖",
      "auto_assign_rules": null,
      "created_at": "2026-10-24 13:57:01.81234 +0000 UTC",
      "book_count": 12,
      "is_smart": false
    }
  ],
  "total": 1
}
```

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

## Query parameters

| Param | Type | Default | Notes |
| ----- | ---- | ------- | ----- |
| include_auto | boolean | `false` | include smart collections |
| sort_by | string | — | `name` sorts alphabetically; otherwise service order |
| library_id | uuid | — | scopes book counts to one library (smart collections only) |

## Response fields

| Field | Type | Notes |
| ----- | ---- | ----- |
| collections | array | `CollectionSummary` objects, see below |
| total | number | length of `collections` |

### Collection item

| Field | Type | Notes |
| ----- | ---- | ----- |
| id | string (uuid) | |
| name | string | |
| description | string | |
| color | string | |
| icon | string | |
| auto_assign_rules | array \| null | raw rules JSON; non-null implies smart |
| created_at | string | Go `time.String()` format |
| book_count | number | live count; respects `library_id` for smart collections |
| is_smart | boolean | |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 500 | `{"error": "..."}` | unexpected server error |