Skip to content

API Reference

Jump to bottom
Luc Garrabos edited this page May 6, 2026 · 1 revision

API Reference

Complete reference of BookStorage HTTP routes and REST API endpoints. All routes are registered in cmd/bookstorage/main.go.

Table of contents

Public endpoints

These endpoints do not require authentication.

Method Path Description
GET / Home page
GET /legal Legal notice page
GET /lang/{lang} Set UI language
GET /healthz Health check (JSON: ok, version, uptime_sec + DB ping)
GET /metrics Prometheus metrics (access controlled by token or loopback)
GET /register Registration page
POST /register Submit registration
GET /login Login page
POST /login Submit login
GET /logout Logout and clear session

Health check response

{
  "ok": true,
  "version": "5.9.2",
  "uptime_sec": 3600
}

Authentication endpoints

Local authentication

Login and registration are handled via the /login and /register pages (form POST).

Google OAuth

Method Path Description
GET /auth/google Start Google OAuth flow
GET /auth/google/callback Google OAuth callback
GET /auth/google/link Link Google account (requires login)
POST /profile/google/unlink Unlink Google account (requires login, desktop only)

See Authentication and Security for details on the OAuth flow and session management.

Works API (authenticated)

All /api/works endpoints require an active session. Unauthenticated requests return 401 with {"error":"session_expired"}.

Method Path Description
GET /api/works List works (paginated, filterable, sortable)
GET /api/works/{id} Get a single work
POST /api/works Create a new work
PATCH /api/works/{id} Update a work
DELETE /api/works/{id} Delete a work

List works — query parameters

Parameter Description Example
page Page number (1-based) ?page=2
limit Items per page ?limit=20
status Filter by status ?status=En cours
reading_type Filter by reading type ?reading_type=Manga
search Search by title ?search=naruto
sort Sort field ?sort=title

List works — response

{
  "data": [
    {
      "id": 1,
      "title": "One Piece",
      "chapter": 1120,
      "status": "En cours",
      "reading_type": "Manga",
      "rating": 5,
      "notes": "",
      "link": "https://...",
      "image_path": "/static/images/onepiece.jpg",
      "updated_at": "2026-05-06T12:00:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Chapter tracking (authenticated)

Method Path Description
POST /api/increment/{id} Increment chapter count by 1
POST /api/decrement/{id} Decrement chapter count by 1
POST /api/set-chapter/{id} Set chapter to a specific value

Catalog and recommendations (authenticated)

Method Path Description
GET /api/catalog/search Search AniList / MangaDex catalog
GET /api/recommendations Get personalized recommendations based on library
POST /api/recommendations/dismiss Dismiss a recommendation
GET /api/recommendations/media Get recommendation media details (with optional translation)
GET /api/stats Get reading statistics

Reading sites (authenticated)

Method Path Description
GET /reading-sites Reading sites management page (desktop)
POST /reading-sites/edit Add or edit a reading site
POST /reading-sites/delete Delete a reading site
POST /reading-sites/probe Probe a single reading site
POST /reading-sites/probe-all Probe all reading sites
GET /api/reading-sites/match Auto-match a URL to a reading site

User pages and tools (authenticated)

Method Path Description
GET /dashboard Main dashboard
GET /stats Statistics page (desktop only)
GET /profile User profile (desktop only)
POST /profile/logout_all Revoke all sessions (desktop only)
POST /profile/delete Delete user account (desktop only)
GET /add_work Add work page
GET /edit/{id} Edit work page
GET /delete/{id} Delete work confirmation
POST /api/delete/{id} Delete work (API)
GET /export Export library (desktop only)
POST /import Import library (desktop only)
GET /tools Tools page (desktop only)
GET /tools/csv-import CSV import tool (desktop only)
GET /tools/duplicates Duplicate detection (desktop only)
POST /tools/duplicates/merge Merge duplicate works (desktop only)
GET /users Browse public user libraries (desktop only)
GET /users/{id} View a user's public library (desktop only)
POST /users/{user_id}/import/{work_id} Import a work from another user's library

Admin endpoints

Require is_admin role. Pages marked "web only" are blocked on mobile.

Method Path Description
GET /admin/accounts Account management
GET /admin/monitoring Prometheus monitoring dashboard (web only)
GET /admin/database Database management (web only)
GET /admin/enrich Catalog enrichment tools (web only)
GET /admin/update Application update page (web only)
GET /admin/approve/{id} Approve a pending account
GET /admin/delete_account/{id} Delete a user account
GET /admin/promote/{id} Promote a user to admin
POST /api/admin/database/delete Delete database entries (web only)
POST /api/admin/enrich/run Run catalog enrichment batch (web only)
GET /api/admin/enrich/queue Get enrichment queue status (web only)
POST /api/admin/enrich/search Search catalog for enrichment (web only)
GET /api/admin/enrich/works List works for enrichment (web only)
POST /api/admin/enrich/link Link a work to a catalog entry (web only)
POST /api/admin/enrich/unlink Unlink a work from catalog (web only)
POST /api/admin/enrich/opt-out Opt out a work from auto-enrichment (web only)
POST /api/admin/enrich/opt-in Opt in a work for auto-enrichment (web only)
GET /api/admin/prometheus/summary Prometheus metrics summary (web only)
POST /api/admin/update/latest Update to latest release (web only)
POST /api/admin/update/latest-major Update to latest major release (web only)
GET /api/admin/update/status Get update status (web only)

Super-admin endpoints

Require both is_admin and is_superadmin roles. Web only.

Method Path Description
GET /admin/migrate-postgres SQLite to PostgreSQL migration page
POST /api/admin/migrate-postgres/test Test PostgreSQL connection
POST /api/admin/migrate-postgres/run Run SQLite to PostgreSQL migration

Response format

Paginated list responses

API list endpoints return a data array with a meta object:

{
  "data": [],
  "meta": {
    "total": 0,
    "total_pages": 0,
    "has_next": false,
    "has_prev": false
  }
}

Single resource responses

Single resource endpoints return the resource object directly.

Error handling

Authentication errors

When an unauthenticated request hits an /api/* endpoint:

{
  "error": "session_expired"
}

HTTP status: 401 Unauthorized.

For non-API routes, unauthenticated users are redirected to /login.

HTTP methods

Unsupported methods return 405 Method Not Allowed (e.g. POST on GET-only endpoints like /healthz).

Middleware chain

All requests pass through this middleware chain (outermost to innermost):

  1. AccessLog — request logging
  2. RequestID — unique request identifier
  3. SecurityHeaders — security response headers
  4. ErrorPages — custom error pages
  5. DatabaseUnavailable — 503 if DB is unreachable
  6. RequestPolicies — origin/referer checks, rate limiting

Then per-route:

  • RequireLogin — session validation
  • RequireAdmin — admin role check
  • RequireSuperadmin — superadmin role check
  • RequireWebOnly — blocks mobile PWA access
  • MobileRedirectToDashboard — redirects mobile to dashboard

Architecture — Next: understand the project structure and tech stack.

BookStorage Wiki

Clone this wiki locally