API reference

Bibliogon's REST API is documented by FastAPI's auto-generated OpenAPI schema. There is no hand-maintained per-endpoint reference page in this docs site — that would drift the moment a new endpoint shipped. Instead, point your client at the live runtime endpoints below.

Live endpoints (when Bibliogon is running)

Endpoint	What it serves
http://localhost:7880/api/docs	Interactive Swagger UI. Try requests directly from the browser. Available only when BIBLIOGON_DEBUG=true.
http://localhost:7880/api/redoc	ReDoc rendering of the same schema. Available only when BIBLIOGON_DEBUG=true.
http://localhost:7880/api/openapi.json	Raw OpenAPI 3.1 schema. The machine-readable source of truth. Available only when BIBLIOGON_DEBUG=true.
http://localhost:7880/api/health	Liveness check. Returns 200 with {"status": "ok"} when the DB is reachable and plugins are loaded. Always available.

Production deployments (BIBLIOGON_DEBUG=false) intentionally hide /api/docs, /api/redoc, and /api/openapi.json to reduce surface area. Enable debug mode locally to read the schema.

Authentication

Bibliogon is local-first and unauthenticated by design — there is no user account system. All API calls succeed without credentials when reaching the local instance. The threat model assumes the host machine is the trust boundary; if you reach the API, you have full access.

Implications:

• Do not expose Bibliogon's API to the public internet. Even behind a reverse proxy, add basic-auth or your reverse proxy's auth layer if multiple users need to share an instance.
• /api/test/reset is gated by BIBLIOGON_DEBUG=true — it deletes all books, articles, chapters, and assets. The debug-flag gate is the only protection.
• The Bibliogon launcher binds to localhost by default; the Docker production setup binds to the host on BIBLIOGON_PORT. Reverse-proxy in front of public deployments.

A real auth layer (multi-user, RBAC, session tokens) is out of scope for the current single-author / local-first phase. If you need multi-tenant Bibliogon, the architecture supports it but the work is not scheduled.

Schema generation

The OpenAPI 3.1 schema at /api/openapi.json is auto-generated by FastAPI from the Pydantic v2 schemas declared on every route. To use it programmatically:

# Pull the schema (requires BIBLIOGON_DEBUG=true)
curl -s http://localhost:7880/api/openapi.json > openapi.json

# Generate a Python client
poetry add --group dev openapi-python-client
poetry run openapi-python-client generate --path openapi.json

# Generate a TypeScript client
npx openapi-typescript openapi.json -o api-types.ts

Bibliogon's own frontend uses neither — frontend/src/api/client.ts hand-writes the API surface as typed methods. That is the single source of truth on the frontend side and is the recommended pattern for any in-tree consumer.

Stable contracts

The endpoints under /api/books, /api/articles, /api/chapters, /api/assets, /api/templates, /api/chapter-templates, /api/backup are stable. New optional fields can be added; existing fields keep their shape and types across minor releases.

Plugin-owned endpoints under /api/{plugin-name}/* follow the plugin's own version, not the Bibliogon release version. Plugin versions are independent of the app version (see Architecture). Read the plugin source for its endpoint contract.

/api/test/reset is explicitly unstable and debug-only. Do not depend on it in production scripts.

High-level overview

For a topic-organized read of the API rather than the schema dump, see docs/API.md. That file groups endpoints by feature area (Books, Chapters, Backup, Plugins, AI, ...) but is hand-maintained — when in doubt, the OpenAPI schema wins.

Last verified for v0.29.0 (2026-05-07).