The Calibre server API — reference
Technical dossier and design. This document preserves studies and the intended architecture. Not every feature described is necessarily available; the user guide and code explain current behaviour.
Compiled on 30 October 2026 from Calibre's source code (src/calibre/srv/), rather than documentation: none exists. Implemented and covered by tests in Packages/Core/Sources/CalibreKit.
1. A warning from the maintainer himself
When asked about documentation for the /ajax API, Kovid Goyal says none exists, that this surface is neither public nor stable, and that you must read the source. The resulting decisions in CalibreKit :
- all decoding is tolerant — a missing, unexpected or
nullfield never causes a library listing to fail; - the server type is detected when connecting (
detectFlavor()), because Calibre-Web returns 404 for all/ajax/*and only offers OPDS; - OPDS remains the fallback, as a standardised and stable option;
- tests preserve real byte formats so a Calibre upgrade breaks a test rather than the application.
2. Three library naming conventions
This is the main trap in this API. It is encoded once in CalibreClient.url(path:query:libraryInQuery:) and checked by four tests.
| Route family | Where library_id |
|---|---|
/ajax/…, /get/… | path component — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | query parameter — ?library_id=Calibre_Library |
/book-…-last-read-position/… | path component, again |
Verified in srv/utils.py : get_library_data() reads rd.query.get('library_id').
3. Catalogue — srv/ajax.py
| Route | Returns |
|---|---|
GET /ajax/library-info | {library_map, default_library} — also used to identify the server type |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parameters query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | dictionary keyed by ID, null for a forbidden book |
GET /ajax/book/{id}/{library} | a book's metadata |
GET /ajax/categories/{library} | top-level categories |
GET /ajax/category/{nom}/{library} | paginated contents of a category |
GET /ajax/books_in/{cat}/{item}/{library} | IDs in a category |
Two decoding traps, both covered by tests:
The ID is not in the object. /ajax/books keys its dictionary by ID without repeating it inside. CalibreKit injects it through the decoder's userInfo .
0101-01-01T00:00:00+00:00 means “no date”. This is Calibre's UNDEFINED_DATE sentinel. Naively decoding it produces a book published in antiquity. CalibreDate converts it back to nil.
4. Conversion — srv/convert.py
This finding changes the architecture: the Calibre server converts over HTTP.
| Route | Method | Role |
|---|---|---|
/conversion/book-data/{id} | GET | input formats, output formats and accepted options |
/conversion/start/{id} | POST | body {input_fmt, output_fmt, options} → returns a job ID |
/conversion/status/{job} | POST | {running, percent, msg} then the terminal state; ?abort_job=1 cancels |
Details found in the source, all significant in practice:
- POST only (
receive_data_methods = {'POST'}). GET is rejected. input_fmtmust be a format the book actually has : the server builds the source path from it and rejects anything else. It expects uppercase, withoutput_fmtin lowercase.- Status is consumed on the first terminal read :
del conversion_jobs[job_id], thencleanup()in afinally. The conclusion can only be read once. Only the user who started the job, in the same library, can query it.CalibreKit.convert(…)encapsulates the polling loop so callers do not need to think about this. - The resulting format is added to the book in the library :
db.add_format(book_id, fmt, output_path). Work is therefore done once, and all devices can subsequently use it through/get/EPUB/{id}. - Recipe files are rejected because they execute code, and certain options are forbidden over the network.
The complete flow, as implemented by CalibreKit :
GET /conversion/book-data/42?library_id=L → entrées : AZW3, PDF ; sorties : epub, mobi, …
POST /conversion/start/42?library_id=L → 17
{"input_fmt":"AZW3","output_fmt":"epub","options":{}}
POST /conversion/status/17?library_id=L → {"running":true,"percent":10,"msg":"Lecture"}
POST /conversion/status/17?library_id=L → {"running":false,"ok":true,"fmt":"epub","size":912345}
GET /get/EPUB/42/L → le fichier, désormais dans la bibliothèque
5. Reading position and annotations — srv/books.py
Calibre already synchronises reading positions on the server.
| Route | Method | Role |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | known positions, by device |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | saves {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | highlights and notes |
/book-manifest/{id}/{FMT} | GET | the server normalises any format into a manifest for its own reader |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | a resource from the normalised book |
/book-get-storage/{library}/{id}/{FMT} | GET | storage status |
Two consequences for Podbook:
We can drop the .jsonl logs described in the initial specifications, at least as the primary mechanism: Calibre already stores a position per device, book and format. Logs remain useful for things Calibre does not know about — audio position and vocabulary.
/book-manifest is a shortcut worth evaluating. The server already converts any format into a normalised structure for its web reader. This overlaps with part of what BookKit was meant to do. Investigate before writing the parser: the manifest format is internal to Calibre and should be treated like the /ajax surface, with care.
srv/kosync.py also exposes KOReader's synchronisation protocol (/kosync/users/auth, /kosync/syncs/progress), another possible route already adopted by other readers.
6. Full-text search — srv/fts.py
| Route | Method | Role |
|---|---|---|
/fts/search | GET | search inside book text, not just metadata |
/fts/snippets/{book_ids} | GET | excerpts with context |
/fts/reindex, /fts/indexing, /fts/disable | POST | index management |
The index must be enabled on the server. Podbook therefore does not need to index the library itself for global search — only books imported outside Calibre.
7. Writing to the library — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L runs a calibredb subcommand on the server. This is the supported way to write: metadata.db does not tolerate a second writer.
Available commands: add, add_format, remove, remove_format, set_metadata, set_custom, add_custom_column, remove_custom_column, custom_columns, annotations, search, list, list_categories, items, notes, data_files, embed_metadata, export, catalog, saved_searches, virtual_libraries, fts_index, fts_search, check_library, backup_metadata, restore_database, clone, trash.
set_custom allows Podbook's processing state to be written cleanly into a custom #podbook column visible in Calibre.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stable and advertised through Bonjour on the local network. This is the fallback when /ajax is unavailable — particularly with Calibre-Web.
9. What this changes for Podbook
| Initial assumption | Reality |
|---|---|
| A MOBI parser needs to be written | Already false in v1: ebook-convert was already sufficient |
| Conversion requires a workshop on the Mac | False : calibre-server converts over HTTP. The iPad requests, the server works and the library gains a format |
| Podbook must invent reading-position synchronisation | Partly false : Calibre already stores one per device |
| Podbook must index for global search | False : /fts/search exists |
metadata.db is read-only, with no writes possible | False : /cdb/cmd/… is the official write interface |
The /ajax API is a solid foundation | False : neither public nor stable. Hence tolerant decoding, type detection and OPDS fallback |
Still true: DRM-protected files will not open, and a Calibre server must be running somewhere for conversion and global search to be available.