bookhoard/docs/developer/api/dashboard.md

Dashboard API

Get Dashboard Sections

Retrieve all dashboard sections for a specific library, including system collections and user collections.

Endpoint: GET /api/dashboard/sections

Authentication: Required (Bearer token)

Query Parameters

Parameter	Type	Required	Description
library_id	string	Yes	Library UUID to fetch sections for
limit	number	No	Items per section (default: 20, max: 100)

Response

Returns array of sections in user's customized order (respects collection_order and hidden_collections preferences).

Section Types:

• is_system: true: System collections (4 pre-seeded defaults)
• is_system: false: User-created collections with show_on_dashboard: true

System Collections:

ID	Title	Icon	Description
continue-reading	Continue Reading	📖	Books with progress > 0% and < 100%
recently-added	Recently Added	🆕	Newest items in library
recently-read	Recently Read	✅	Books with progress = 100%
not-started	Not Started	📕	Books with no reading progress

Example Response

{
  "sections": [
    {
      "id": "continue-reading",
      "is_system": true,
      "title": "Continue Reading",
      "description": "Books you're currently reading (0 < progress < 1)",
      "icon": "📖",
      "items": [
        {
          "media_item_id": "uuid-here",
          "title": "Book Title",
          "author": "Author Name",
          "cover_image_path": "/path/to/cover.jpg"
        }
      ],
      "view_all_url": "/section/continue-reading",
      "priority": 1
    },
    {
      "id": "collection-uuid",
      "is_system": false,
      "title": "My Favorites",
      "description": "My favorite books",
      "icon": "⭐",
      "items": [],
      "view_all_url": "",
      "priority": 100
    }
  ]
}

User Preferences

The endpoint respects user's dashboard preferences:

• collection_order: Sections returned in user's custom order
• hidden_collections: Hidden collections excluded from response
• items_per_section: Default limit from user preferences (overridden by ?limit= query param)

Update Dashboard Preferences

Save or update user dashboard preferences for a specific library.

Endpoint: PUT /api/dashboard/preferences

Authentication: Required (Bearer token)

Request Body

{
  "library_id": "uuid",
  "hidden_collections": ["not-started"],
  "collection_order": ["recently-added", "continue-reading", "recently-read"],
  "items_per_section": 20
}

Response

Returns updated preferences object.

Restore System Collection

Reset a system collection to its default state (removes user customizations).

Endpoint: POST /api/dashboard/restore-system-collection

Authentication: Required (Bearer token)

Request Body

{
  "collection_name": "continue-reading"
}

Valid collection_name values:

• continue-reading
• recently-added
• recently-read
• not-started

Response

{
  "message": "System collection restored to defaults"
}

Error Responses

Status	Description
400	Missing library_id
400	Invalid library_id
400	Invalid collection_name
401	Unauthorized
500	Failed to load sections
500	Failed to save preferences
500	Failed to restore collection