API Reference

Leelaa Reader exposes stable APIs for authentication, license status, library browsing, categories, playback, progress, favorites, and bookmarks.

OpenAPI

• Swagger UI
• OpenAPI YAML

Administrative operations such as importing, deleting, scanning, system configuration, log maintenance, and AI maintenance are not part of the stable third-party contract.

Base URL

http://{host}:8686/api/v1

Same-origin deployments may use /api/v1, while fnOS gateway deployments may use /app/leelaa-reader/api/v1.

Minimum flow

1. POST /auth/login
2. GET /license/status
3. GET /books or GET /books/search
4. GET /books/{bookId} and GET /books/{bookId}/chapters
5. GET /books/{bookId}/download-manifest
6. GET /chapters/{chapterId}/play?raw=1
7. Read /auth/reading-progress/{bookId}; writes require the identity headers above

Authentication

Authorization: Bearer {token}

For players that cannot attach headers:

/api/v1/chapters/{chapterId}/play?raw=1&access_token={token}

Do not persist user passwords. Re-authenticate after 401. Stop playback and background synchronization after 403 license_required.

Sync write identity headers

Progress and playback-settings write endpoints (POST/DELETE /auth/reading-progress/{bookId}, POST /auth/reading-progress/batch, POST/DELETE /auth/playback-settings/{bookId}) require two identity headers in addition to the Bearer token. They prevent progress from being written to the wrong server instance or account:

X-Leelaa-Expected-Server-Id: {serverId}
X-Leelaa-Expected-User-Id: {userId}

Both values come from the login response POST /auth/login: data.serverId and data.user.id. Cache them after login. The serverId changes when the server instance is rebuilt, so re-login to refresh it.

Status	code	Cause
428	listening_scope_required	Either identity header is missing
400	listening_scope_invalid	User-Id is not a number
409	listening_scope_mismatch	Header values do not match this server or the logged-in account

Read endpoints (GET) do not require these headers.

Playback rules

• Use the complete server-provided playback manifest;
• Use chapterId as the persistent chapter identifier;
• Never persist list indexes as progress or bookmark identifiers;
• Do not keep only a partial queue around the current chapter;
• Preserve the server-provided order;
• The server owns progress merge and conflict decisions;
• Do not overwrite valid progress with position 0 during restoration.