A smart list is a saved book or series search — the same BookSearch/SeriesSearch document that POST /api/v1/books/list and POST /api/v1/series/list accept — owned by a user and evaluated live on each request through the same query path. Membership is never stored, so conditions that depend on the requesting user (read status, content restrictions, library authorization) always evaluate for whoever is asking, not for whoever saved the list. Not part of the Komga API surface; the endpoints are included in the OpenAPI document under the Smart lists (kmrs extension) tag.
Managing lists
GET/POST /api/v1/smart-lists and GET/PATCH/DELETE /api/v1/smart-lists/{id} — any authenticated user can create lists, and a name only has to be unique per owner. The search document is validated against the list target (BOOK or SERIES) when written, and switching the target requires sending a new search document.
Each list has a visibility scope:
PRIVATE(default) — owner and admins onlyPUBLIC— every authenticated userSHARED— the users named insharedWithUserIds, validated against existing users; aSHAREDlist always requires a non-empty scope
Visibility and sharing are admin capabilities: a regular user’s lists are always private, and GET /api/v1/smart-lists/share-targets (the user directory for picking share targets) is admin-only, like komga’s /api/v2/users. Visibility grants read access only: renaming, changing the filter or the scope, and deleting the list stay with the owner and admins; covers stay with the owner. Admins see every list and can narrow the listing with ?owner=<userId>.
Reading the items
POST /api/v1/smart-lists/{id}/books and POST /api/v1/smart-lists/{id}/series evaluate the stored filter for the requesting user and return the same paged DTOs as the /list endpoints. The optional request body is an overlay search document: its conditions are ANDed with the stored filter, and its full-text term replaces the stored one — this is how a list detail page applies its own filters and search box on top of the saved filter.
Covers
GET /api/v1/smart-lists/{id}/thumbnail serves a generated mosaic of up to 4 covers of the matched books or series (the collection collage), cached behind a content fingerprint and rebuilt when the matched set changes. The mosaic is computed once from the owner’s view, so on shared lists a sharee with stricter restrictions may see covers their own filter would hide. Uploading, listing, selecting, and deleting covers under /thumbnails mirrors the read-list cover API, with writes restricted to the owner; a selected uploaded cover wins over the mosaic.
Smart lists and their covers live in kmrs.sqlite, so the Java version can always open a kmrs data directory. Changes are delivered over SSE (SmartListAdded / SmartListChanged / SmartListDeleted / SmartListThumbnailChanged) to everyone in the visibility scope — the owner, admins, every authenticated user for PUBLIC, and the share scope for SHARED; webhooks do not carry smart-list events.
The Java version has no smart lists.