--- method: GET path: /api/media-items/search auth: jwt area: media-items --- # Search Media Items (Unified):<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/create_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/update_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|channel|>Edited docs/developer/api/media-items/delete_media_item.md (1 replacement)<|end|><|start|>edit to=assistant<|channel|>analysis<|message|>Edited docs/developer/api/media-items/search_media_items.md (1 replacement) Search and filter media items with fuzzy matching support. **Note:** All text filters use fuzzy matching via PostgreSQL pg_trgm (threshold: 0.3 similarity). This handles typos and partial matches automatically. Use quotes for exact match. **Endpoint**: `GET /api/media-items/search` **Auth**: Required ## Query Parameters ### Search Parameters | Parameter | Type | Required | Description | | ---------- | ------- | -------- | ---------------------------------------------------- | | q | string | No | Search query (fuzzy by default, exact in quotes) | | library_id | string | Yes | Filter to specific library (UUID) | | limit | integer | No | Number of results (default 50, max 200) | | offset | integer | No | Number to skip for pagination | ### Filter Parameters (All Fuzzy Except Years/Booleans) | Parameter | Type | Description | | -------------- | ------- | --------------------------------------------------- | | author_filter | string | Fuzzy match author field | | series_filter | string | Fuzzy match series field | | tags_filter | string | **Fuzzy match tags array** | | language_filter| string | Fuzzy match language field | | year_min | integer | Minimum copyright year (exact range) | | year_max | integer | Maximum copyright year (exact range) | | has_cover | boolean | Filter by cover image presence (exact boolean) | ### Autocomplete Parameters (Field-Specific Search) | Parameter | Type | Description | | ---------- | ------ | ---------------------------------------------- | | authors | string | Search author values for autocomplete dropdown | | tagss | string | Search tags values for autocomplete dropdown | | series | string | Search series values for autocomplete dropdown | | languages | string | Search language values for autocomplete | ## Request Headers | Header | Type | Required | Description | | ------------- | ------ | -------- | ------------ | | Authorization | string | Yes | Bearer token | ## Search Behavior ### Fuzzy Search (Default) Handles typos and partial matches automatically: - `"asimov"` → matches "Asimov, Isaac", "Asimov, Foundation" - `"scifi"` → matches "Sci-Fi", "Science Fiction" - `"azimov"` → matches "Asimov, Isaac" (typo tolerance) ### Exact Search (With Quotes) Use double quotes for exact phrase matching: - `"\"Foundation and Empire\""` → only "Foundation and Empire" - `"\"Asimov, Isaac\""` → only "Asimov, Isaac" ### Filter Behavior **Text filters (fuzzy):** - `author_filter=asimov` → fuzzy matches author field - `tags_filter=scifi` → fuzzy matches tags field **Exact filters:** - `year_min=2000&year_max=2010` → exact year range - `has_cover=true` → exact boolean match ## Example Requests ### 1. Global Fuzzy Search Search all fields for "foundation": ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&q=foundation Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 2. Fuzzy Author Filter Find books by "asimov" (matches "Asimov, Isaac"): ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&author_filter=asimov Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 3. Combined Search + Filters Search "foundation" within books by "asimov": ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&q=foundation&author_filter=asimov Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 4. Exact Match with Quotes Exact phrase search: ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&q="Foundation%20and%20Empire" Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 5. Multiple Fuzzy Filters Fiction books from 2000-2010: ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&tags_filter=fiction&year_min=2000&year_max=2010 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 6. Field-Specific Search (Autocomplete) Get author values for dropdown: ```http GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&authors=asimov&limit=50 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Response:** ```json { "results": [ {"value": "Asimov, Isaac", "count": 47, "score": 0.8}, {"value": "Asimov, Isaac & Robert Silverberg", "count": 2, "score": 0.75} ], "total": 2 } ``` ## Response (200 OK) **Media items search:** ```json example-response [ { "id": "uuid", "title": "Foundation", "author": "Isaac Asimov", "tags": [ "Science Fiction", "Adventure" ], "library_id": "uuid", "library_name": "E-Books", "abridged": null, "added_by_admin_id": null, "age_rating": null, "alternate_info": null, "archived_at": null, "asin": null, "audio_metadata": null, "authors": null, "authors_search": null, "chapter_count": null, "chapter_metadata": null, "community_rating": null, "contributors": null, "contributors_search": null, "copyright_year": null, "cover_image_path": null, "created_at": null, "date_published": null, "description": null, "edition": null, "entitlement_id": null, "explicit": null, "file_path": null, "file_sha256": null, "file_size": null, "format_group": null, "format_mimetype": null, "genre": null, "goodreads_id": null, "google_books_id": null, "has_fixed_layout": null, "hash_confidence": null, "imported_at": null, "imprint": null, "is_black_and_white": null, "is_reflowable": null, "isbn": null, "kobo_content_id": null, "kobo_metadata": null, "language": null, "library_type_name": null, "library_type_name_2": null, "manga_type": null, "metadata_notes": null, "metadata_overrides": null, "mime_type": null, "missing_scan_count": null, "narrators": null, "narrators_search": null, "openlibrary_id": null, "opf_identifier": null, "opf_uuid": null, "page_count": null, "publisher": null, "publishers": null, "publishers_search": null, "reading_direction": null, "revision_number": null, "scan_information": null, "series": null, "series_count": null, "series_number": null, "story_arc": null, "subtitle": null, "summary": null, "tags_search": null, "total_characters": null, "updated_at": null, "volume": null, "web_url": null } ] ``` **Field values search (autocomplete):** ```json { "results": [ {"value": "Asimov, Isaac", "count": 47, "score": 0.8} ], "total": 1 } ``` ## Error Responses | Code | Description | | ---- | ---------------------------- | | 400 | Invalid library_id | | 400 | Missing library_id | | 401 | Invalid or expired token | | 404 | No results found | ### Backward Compatibility The `genre_filter` parameter is **deprecated but still supported** for backward compatibility. It will return 0 results for books imported from Calibre (genre field is NULL).