Overview
Biblon is a unified book catalog providing bibliographic metadata and cover images with full-text search. Other domains — POS, EC, inbound, returns, buyback, analytics — consume catalog data but are not part of this service.
What Biblon owns
- Book identity (ISBN-13 with checksum validation; internal codes for ISBN-less items)
- Bibliographic metadata (title, author, publisher, dates, series, description)
- Pricing metadata (list price, cost, net rate)
- Classification (category tags, C-code, condition, contract type)
- Cover images (ingestion, HTTPS normalization, and automatic fallback lookup)
- Metadata enrichment (waterfall ISBN lookup and AI-assisted cover analysis)
What Biblon does not own
- Inventory quantities and stock management
- Sales transactions (POS, EC orders)
- Return and buyback processing logic
- Supplier management, analytics, reporting
Authentication
All /api/* endpoints require a bearer API key. /health is unauthenticated.
Authorization: Bearer biblon_<env>_<random>Keys are per-consumer, issued by the Valuebooks platform team, and stored hashed on the server. Each consuming service holds its own key in its own secret store — there is no shared password. On 401 the API responds with WWW-Authenticate: Bearer realm="Biblon API".
Example
curl -H "Authorization: Bearer $BIBLON_KEY" \
"$BIBLON_URL/api/books?isbn=9784101010137"API Reference
The full OpenAPI 3.1 specification is available at /openapi.yaml.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Liveness check (no auth) |
| GET | /api/books/search | Full-text search (title, author, publisher, ISBN) |
| GET | /api/books/:id | Get edition by numeric DB id |
| GET | /api/books?isbn= | Get edition by ISBN-13 |
| GET | /api/books?catalog= | Get edition by catalog id (VC + 8 chars) |
| POST | /api/books | Upsert edition (ISBN dedup → title+author fallback) |
| POST | /api/books/batch | Batch lookup by ids |
| GET | /api/isbn/validate | Validate and normalize ISBN |
| GET | /api/isbn/convert | Convert ISBN-10 to ISBN-13 |
| GET | /api/admin/* | Admin console backend (same bearer auth) |
Catalog ID
Each edition has a stable catalogId — a VC prefix followed by 8 lowercase alphanumeric characters (e.g., VC4f7kx2q9). This is the identifier consuming services should use for cross-service references.