Checks that calibredb is reachable and the library responds. Use it first to diagnose the configuration (calibredb path, library, etc.).

Searches books using Calibre's search syntax and returns JSON. Example queries: 'tag:Philosophy and author:Plato', 'series:"Classics"', 'title:Republic', 'pubdate:>2010'. Leave query empty to list (use limit).

Returns ALL metadata for a book by its id (JSON).

Lists the values of a category with their book counts, as CSV. category accepts: tags, authors, series, publisher, languages, formats, rating, identifiers.

Library summary: total number of books and a breakdown by category (tags, authors, series, formats).

Sets (REPLACES) a book's metadata. 'fields' is an object of field:value pairs. Fields: title, title_sort, authors (multiple with ' & '), author_sort ('Last, First'), tags (comma-separated), series, series_index, publisher, pubdate ('2020-01-01'), languages ('eng'/'spa'), rating (0–10, where 10 = 5 stars), comments (HTML allowed), identifiers ('isbn:9788491050000'), cover (path to an image). NOTE: it replaces the whole field value; to keep the other tags use add_tags/remove_tags.

Adds tags to a book WITHOUT removing the existing ones. Multiple tags comma-separated.

Removes specific tags from a book, keeping the rest.

Renames a tag across the WHOLE library (on every book that has it).

Applies the same metadata to ALL books matching a search. Useful for organizing in bulk (e.g. setting a series or publisher on a group). 'query' uses Calibre syntax; 'fields' works like set_metadata (replaces the field). To add tags in bulk without removing, call add_tags per book.

Adds a file (EPUB/PDF/MOBI/AZW3...) to the library. Returns the new id. automerge (optional): 'ignore' | 'overwrite' | 'new_record' to handle duplicates. identifiers e.g. 'isbn:9788491050000'.

Removes books from the library by id (comma-separated). DESTRUCTIVE: requires confirm=true. permanent=true skips Calibre's recycle bin.

Converts a book to another format and ADDS that format to the same library book (does not create a new book). Ideal for generating AZW3 for Kindle. If you don't pass source_format, it picks the best available (epub > azw3 > mobi > fb2 > pdf).

Exports books to a folder on disk (e.g. to copy them to a Kindle). book_ids comma-separated or 'all'. formats optional, e.g. 'azw3,epub'.

Detects likely duplicates by grouping on normalized (title, author). Returns the groups with more than one book.

Lists books that are missing a specific metadata field. missing accepts: tags, comments, series, publisher, cover, identifiers, languages, pubdate.

Looks up metadata from online sources (Google Books, etc.) by title/author or ISBN and returns an OPF. If you pass apply_to_book_id, it applies that metadata (and optionally the cover) to that book in your library.