API

API

Both servers publish an OpenAPI specification describing every endpoint, its parameters, and the shape of each response. You can paste either spec into Swagger Editor or any OpenAPI viewer to browse it interactively.

Updater API

The updater's web page serves its API at http://localhost:<port>/api/… (whatever port --web was given). The spec is a hand-written YAML file, served live and committed in the repository:

Where	What
GET /api/openapi.yaml	The live spec, from the running instance
docs/updater-openapi.yaml	The same file on GitHub

Every endpoint is under /api/ and returns JSON. All responses include Cache-Control: no-store. Errors are {"error": "..."}. Operations that take time (updates, chapter detection, plugin installs) return {"queued": <id>, "label": "..."} and their progress appears in GET /api/state.

Authentication: the API is behind the same HTTP Basic password as the web page when MIRROR_WEB_PASSWORD is set. Without a password, anyone who can reach the port can call any endpoint.

Endpoint groups

Tag	What	Examples
Library	Comics in the library and their details	GET /api/comics, GET /api/comic?name=…
Running	Updates, the job queue, and stopping jobs	GET /api/state, POST /api/update, POST /api/stop
Chapters	Chapter detection, correction, page insertion	POST /api/chapterize, POST /api/pages
Elements	XPath element paths for finding images and links	GET /api/elements, POST /api/check
Config	Library-wide settings	GET /api/config, POST /api/config
Plugins	Scraper plugins — listing, installing, setup	GET /api/plugins, POST /api/plugins/install
Uploads	Uploading and placing comic archives	POST /api/upload, POST /api/upload/place

The full list, with request and response schemas, is in the spec itself.

Reader API

The Reader's API is under http://localhost:<port>/api/… (8082 in the Docker image). Its spec is generated from the FastAPI routes:

Where	What
GET /api/openapi.json	The live spec, from the running instance
docs/reader-openapi.json	An exported copy on GitHub

To regenerate the exported copy after the routes change:

python docs/generate_reader_spec.py

The reader's endpoints cover the library listing, comic pages, reading progress, covers, settings, what a comic - or a whole folder or series - says in its ComicInfo.xml (and how far a change of it being written has got), and a health check. The spec has the details.

Keeping the specs current

The updater spec is hand-written, so it must be updated in the same commit as any endpoint change. The reader spec is generated: run the script above and commit the result. Both are tested — the suites check that the spec endpoints respond and look right.