This is the same HTTP API Bookhoarder’s own web UI calls — there’s no
separate public API surface. It’s useful for scripting against a
self-hosted instance (bulk uploads, automating shelves), but it’s
internal and unversioned: no API keys, no stability guarantee across
releases, and every route lives under the app’s own origin (http://localhost:3000
by default).
Authentication
There’s no login form or token endpoint — identity comes from which
profile is active in the browser, tracked by the bookhoard_profile
cookie.
POST /api/profiles/active sets that cookie: pass a
profile id, and its password if the profile has one set (see
Profiles & Access). Every other endpoint reads the
active profile from the cookie already on the request — script against
this API with a cookie jar, the same way a browser session would.
Three permission levels apply, checked server-side on every request that needs them (not just hidden in the UI):
| Level | Applies to |
|---|---|
| Anyone with a valid session | Reading books, shelves, settings; updating your own reading state |
| The profile itself, or an admin | Editing a profile’s name, color, e-reader email, or password |
| Admin only | Creating/deleting profiles, deleting books, changing roles, changing server-wide settings (SMTP, trending, metadata) |
Conventions
- All request and response bodies are JSON, except book upload
(
multipart/form-data) and file downloads (raw bytes) - A failed request returns a JSON body shaped
{ "error": "..." }with a 4xx or 5xx status — there’s no separate error-code field to switch on - IDs are opaque strings — book IDs are slugs derived from title, profile and shelf IDs are UUIDs
Endpoints by resource
| Resource | Page |
|---|---|
| Profiles — list, create, edit, switch active profile | Profiles |
| Books — upload, list, edit, delete, send to e-reader, metadata lookup | Books |
| Shelves — list, create, edit, delete, add/remove books | Shelves |
| Settings — SMTP, trending, metadata lookup limit | Settings |
| Health, trending, cover/description lookups, file downloads, OPDS catalog | Other endpoints |