Files

T

john-okeefe 5d16e02785 docs: add custom section builder API documentation

Phase 13 - Documentation Updates

- Add complete API documentation for custom section builder
- Document all 14 filter fields with operators
- Include example use cases (Sci-Fi Favorites, High Rated, etc.)
- Document preview endpoint and collection creation
- Verify existing dashboard.md documentation is comprehensive

Part of Carousel Dashboard Plan completion

2026-02-20 10:20:39 -05:00

3.2 KiB

Raw Blame History

Custom Section Builder API

The Custom Section Builder allows users to create personalized dashboard sections by defining filter rules or manually selecting books.

Preview Collection

Evaluates filter rules and returns matching items without saving the collection.

Endpoint: POST /api/collections/preview

Request Body:

{
  "library_id": "uuid",
  "rules": [
    {
      "id": "rule1",
      "field": "genre",
      "operator": "equals",
      "value": "Sci-Fi",
      "priority": 1
    }
  ],
  "manual_book_ids": ["uuid1", "uuid2"],
  "limit": 20
}

Available Filter Fields:

Field	Type	Operators
`title`	text	contains, equals, starts_with, ends_with, regex
`author`	text	contains, equals
`genre`	select	equals, not_equals, in, not_in
`series`	text	is_set, is_not_set, equals, contains
`progress`	number	equals, not_equals, greater_than, less_than, between, is_set, is_not_set
`rating`	number	equals, not_equals, greater_than, less_than, is_set, is_not_set
`date_added`	date	equals, not_equals, before, after, between, last_x_days
`last_read`	date	equals, before, after, between, last_x_days, is_set, is_not_set
`publisher`	text	contains, equals
`language`	select	equals, not_equals, in
`format`	select	equals, in
`tags`	text	contains, not_contains, equals
`narrators`	text	contains, equals, is_set, is_not_set

Response:

{
  "items": [
    {
      "media_item_id": "uuid",
      "title": "Book Title",
      "author": "Author Name",
      "cover_image_path": "/path/to/cover.jpg"
    }
  ]
}

Create Custom Section

Creates a new custom collection with filter rules and/or manual book selection.

Endpoint: POST /api/collections

Request Body:

{
  "name": "My Custom Section",
  "description": "My favorite Sci-Fi books",
  "icon": "📚",
  "color": "#9333ea",
  "show_on_dashboard": true,
  "auto_assign_rules": "[{\"id\":\"rule1\",\"field\":\"genre\",\"operator\":\"equals\",\"value\":\"Sci-Fi\",\"priority\":1}]",
  "manual_book_ids": ["uuid1", "uuid2"],
  "view_settings": {}
}

Response: Returns the created collection object.

Frontend Implementation

Route: /custom-section

Template: templates/custom_section.templ

TypeScript: web/src/custom-section-builder.ts

Key features:

14 filter fields with various operators
Live preview functionality
Search + multi-select for manual book addition
AND/OR logic support for combining rules

Example Use Cases

Sci-Fi Favorites

{
  "rules": [
    {
      "field": "genre",
      "operator": "equals",
      "value": "Sci-Fi"
    }
  ]
}

High Rated Books

{
  "rules": [
    {
      "field": "rating",
      "operator": "greater_than",
      "value": "4"
    }
  ]
}

Long Books (Manual Selection)

{
  "manual_book_ids": ["uuid1", "uuid2", "uuid3"]
}

Recently Finished Audiobooks

{
  "rules": [
    {
      "field": "format",
      "operator": "equals",
      "value": "Audiobook"
    },
    {
      "field": "last_read",
      "operator": "last_x_days",
      "value": "30"
    }
  ]
}

3.2 KiB Raw Blame History