Skip to main content

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 null field 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 familyWhere 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​

RouteReturns
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,3dictionary 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.

RouteMethodRole
/conversion/book-data/{id}GETinput formats, output formats and accepted options
/conversion/start/{id}POSTbody {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_fmt must be a format the book actually has : the server builds the source path from it and rejects anything else. It expects uppercase, with output_fmt in lowercase.
  • Status is consumed on the first terminal read : del conversion_jobs[job_id], then cleanup() in a finally. 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.

RouteMethodRole
/book-get-last-read-position/{library}/{id}:{FMT}GETknown positions, by device
/book-set-last-read-position/{library}/{id}/{FMT}POSTsaves {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GEThighlights and notes
/book-manifest/{id}/{FMT}GETthe server normalises any format into a manifest for its own reader
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETa resource from the normalised book
/book-get-storage/{library}/{id}/{FMT}GETstorage 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​

RouteMethodRole
/fts/searchGETsearch inside book text, not just metadata
/fts/snippets/{book_ids}GETexcerpts with context
/fts/reindex, /fts/indexing, /fts/disablePOSTindex 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 assumptionReality
A MOBI parser needs to be writtenAlready false in v1: ebook-convert was already sufficient
Conversion requires a workshop on the MacFalse : calibre-server converts over HTTP. The iPad requests, the server works and the library gains a format
Podbook must invent reading-position synchronisationPartly false : Calibre already stores one per device
Podbook must index for global searchFalse : /fts/search exists
metadata.db is read-only, with no writes possibleFalse : /cdb/cmd/… is the official write interface
The /ajax API is a solid foundationFalse : 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.