API Endpoints#
All API endpoints are prefixed with /api. Endpoints noted as "Requires library card" need a valid library card (JWT token) in the Authorization header.
Librarians#
POST /api/librarians/register#
Register a new librarian account.
Request body:
{
"username": "ada",
"email": "ada@example.com",
"password": "Lovelace1815!"
}
Response: 201 Created with the librarian profile.
POST /api/librarians/login#
Log in and receive a library card (JWT token).
Request body:
{
"username": "ada",
"password": "Lovelace1815!"
}
Response: Library card with access_token, token_type, and expires_in.
GET /api/librarians/me/xp#
Get the authenticated librarian's XP summary, rank, and recent awards. Requires library card.
GET /api/librarians/me/badges#
Get the authenticated librarian's earned badges. Requires library card.
GET /api/librarians/me/streak#
Get the authenticated librarian's review streak info. Requires library card.
POST /api/librarians/refresh#
Refresh a library card. Requires a valid (non-expired) library card.
Response: New library card with a fresh expiry.
GET /api/librarians/leaderboard#
Get the top librarians ranked by pages read.
Query parameters:
limit(int, default: 10, max: 100) -- Number of entries to return
Volumes#
POST /api/volumes/#
Create a new volume (shelve knowledge).
Request body:
{
"title": "The Art of Code Review",
"content": "A comprehensive guide...",
"shelf_id": 1,
"bookmarks": ["code-review", "best-practices"]
}
Response: 201 Created with the new volume including its Dewey Score.
GET /api/volumes/#
List all volumes in the library.
Query parameters:
page(int, default: 1, min: 1) -- Page numberper_page(int, default: 20, min: 1, max: 100) -- Items per pageshelf_id(int, optional) -- Filter by shelf
Response: Paginated list of volumes.
GET /api/volumes/{volume_id}#
Get a specific volume by ID.
Response: Volume with current Dewey Score.
PATCH /api/volumes/{volume_id}#
Update a volume's title, content, shelf, or bookmarks. Requires library card.
Only the volume's author (or a Head Librarian) may update it; others receive 403.
Request body: Any subset of volume fields.
Response: Updated volume.
DELETE /api/volumes/{volume_id}#
Archive a volume (soft delete). Requires library card. Only the volume's author
(or a Head Librarian) may archive it; others receive 403.
Response: 204 No Content
POST /api/volumes/{volume_id}/review#
Review a volume, resetting its Dewey Score to 100 (pristine).
Response: Updated volume with reset score.
Shelves#
POST /api/shelves/#
Create a new shelf.
Request body:
{
"name": "Software Engineering",
"description": "Volumes about software development practices."
}
Response: 201 Created with the new shelf.
GET /api/shelves/#
List all shelves with volume counts and average Dewey Scores.
GET /api/shelves/{shelf_id}#
Get a specific shelf by ID.
PATCH /api/shelves/{shelf_id}#
Update a shelf's name or description. Requires library card. Only the shelf's
creator (or a Head Librarian) may update it; others receive 403.
DELETE /api/shelves/{shelf_id}#
Delete a shelf and all its volumes. Requires library card. Only the shelf's
creator (or a Head Librarian) may delete it; others receive 403.
Response: 204 No Content
Catalog#
GET /api/catalog/autocomplete#
Get autocomplete suggestions from volume titles.
Query parameters:
q(string, required) -- Search querylimit(int, default: 5, min: 1, max: 50) -- Maximum suggestions
Response: List of title suggestions.
Reading Room#
GET /api/reading-room/health#
Get the library's overall health status.
Response:
{
"status": "healthy",
"mood": "Quiet study",
"description": "Warm golden light fills the reading room.",
"total_volumes": 42,
"overdue_volumes": 3,
"average_dewey_score": 82.5
}
GET /api/reading-room/overdue#
Get a report of volumes needing review.
Response: Lists of overdue volumes and volumes needing attention with their Dewey Scores.
GET /api/reading-room/last-recalc#
Get the timestamp of the last background Dewey Score recalculation.
Bulletins#
POST /api/bulletins/#
Subscribe to webhook notifications for library events.
GET /api/bulletins/#
List your webhook subscriptions.
DELETE /api/bulletins/{bulletin_id}#
Remove a webhook subscription.