Libris

Appearance

API Reference ​

Interactive API documentation generated from the OpenAPI spec.

API Version: 0.1.0

GET /_docs/openapi.json​

GET
/_docs/openapi.json

Responses​

OK

Samples​

GET /_docs/scalar​

GET
/_docs/scalar

Responses​

OK

Samples​

GET /_docs/swagger​

GET
/_docs/swagger

Responses​

OK

Samples​

POST /__test/cleanup​

POST
/__test/cleanup

Responses​

OK

Samples​

POST /__test/invalidate-cache​

POST
/__test/invalidate-cache

Responses​

OK

Samples​

POST /__test/seed-books​

POST
/__test/seed-books

Responses​

OK

Samples​

POST /__test/seed-candidates​

POST
/__test/seed-candidates

Responses​

OK

Samples​

POST /__test/seed-files​

POST
/__test/seed-files

Responses​

OK

Samples​

List API keys​

GET
/api/auth/keys

List all API keys (hashes are never exposed)

Responses​

Array of API key metadata

application/json
JSON
{
  
"keys": [
  
  
{
  
  
  
"id": "string",
  
  
  
"label": "string",
  
  
  
"createdAt": "string",
  
  
  
"lastUsedAt": "string"
  
  
}
  
]
}

Samples​

Create API key​

POST
/api/auth/keys

Generate a new API key with the given label

Request Body​

application/json
JSON
{
  
"label": "string"
}

Responses​

API key created — returns the raw key (shown only once)

application/json
JSON
{
  
"id": "string",
  
"key": "string",
  
"label": "string",
  
"createdAt": "string"
}

Samples​

Delete API key​

DELETE
/api/auth/keys/{id}

Revoke an API key. Cannot delete the last key or the key used for this request.

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Key deleted

application/json
JSON
{
  
"deleted": true,
  
"id": "string"
}

Samples​

Initial setup​

POST
/api/auth/setup

Create the first API key. Only works when no keys exist yet.

Request Body​

application/json
JSON
{
  
"label": "string"
}

Responses​

API key created — returns the raw key (shown only once)

application/json
JSON
{
  
"id": "string",
  
"key": "string",
  
"label": "string",
  
"createdAt": "string"
}

Samples​

Delete book​

DELETE
/api/books/{id}

Delete a book and its associated files from the database and disk

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Book deleted

Samples​

Approve book metadata​

POST
/api/books/{id}/approve

Select metadata fields from candidates, mark book as organized, and enqueue file organization

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
  
"fields": {
  
  
"additionalProperties": {
  
  
  
"source": "string",
  
  
  
"value": {
  
  
  
}
  
  
}
  
}
}

Responses​

Book approved and organize job enqueued

application/json
JSON
{
  
"id": "string",
  
"status": "string",
  
"title": "string",
  
"author": "string",
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Samples​

Get metadata candidates​

GET
/api/books/{id}/candidates

List metadata candidates fetched from external sources for a book

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Book info with metadata candidates

application/json
JSON
{
  
"book": {
  
  
"id": "string",
  
  
"status": "string",
  
  
"title": "string",
  
  
"author": "string"
  
},
  
"candidates": [
  
  
{
  
  
  
"id": "string",
  
  
  
"source": "string",
  
  
  
"normalized": {
  
  
  
},
  
  
  
"confidence": "string",
  
  
  
"selectedFields": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
]
}

Samples​

Check service credentials​

GET
/api/credentials/{service}

Check whether credentials are configured for a service (opds or kosync). Returns the username and timestamps if configured.

Parameters​

Path Parameters

service*
Type
string
Required
Valid values
"opds""kosync""hardcover"

Responses​

Credential status

application/json
JSON
{
  
"configured": true,
  
"service": "string",
  
"username": "string",
  
"createdAt": "string",
  
"updatedAt": "string"
}

Samples​

Set service credentials​

PUT
/api/credentials/{service}

Set or update credentials for a service. Passwords for opds/kosync are bcrypt-hashed. Hardcover tokens are sealed with reversible encryption.

Parameters​

Path Parameters

service*
Type
string
Required
Valid values
"opds""kosync""hardcover""google_books"

Request Body​

application/json
JSON
{
  
"username": "string",
  
"password": "string"
}

Responses​

Credentials updated

application/json
JSON
{
  
"service": "string",
  
"username": "string",
  
"updated": true
}

Samples​

Delete service credentials​

DELETE
/api/credentials/{service}

Remove stored credentials for a service (opds, kosync, or hardcover).

Parameters​

Path Parameters

service*
Type
string
Required
Valid values
"opds""kosync""hardcover"

Responses​

Credentials deleted

application/json
JSON
{
  
"service": "string",
  
"deleted": true
}

Samples​

dashboard​

Operations​

GET/api/dashboard

Get dashboard data​

GET
/api/dashboard

Returns currently reading books, recently added, inbox count, library stats, and pipeline status

Responses​

Dashboard data

application/json
JSON
{
  
"currentlyReading": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"coverPath": "string",
  
  
  
"percentage": 0,
  
  
  
"device": "string",
  
  
  
"lastRead": 0
  
  
}
  
],
  
"recentlyAdded": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"coverPath": "string",
  
  
  
"createdAt": "string"
  
  
}
  
],
  
"inboxCount": 0,
  
"stats": {
  
  
"totalBooks": 0,
  
  
"totalAuthors": 0,
  
  
"topGenre": "string",
  
  
"totalFileSize": 0,
  
  
"processingCount": 0
  
},
  
"pipeline": {
  
  
"additionalProperties": {
  
  
  
"waiting": 0,
  
  
  
"active": 0,
  
  
  
"completed": 0,
  
  
  
"failed": 0,
  
  
  
"delayed": 0
  
  
}
  
}
}

Samples​

events​

Operations​

GET/api/events

Server-Sent Events stream​

GET
/api/events

Parameters​

Query Parameters

bookId

Filter events to only this book ID

Type
string

Responses​

SSE event stream

text/event-stream
JSON
"string"

Samples​

Get Hardcover connection status​

GET
/api/hardcover/status

Check whether a Hardcover credential is configured, verify the token with the Hardcover API, and return the connected username and last sync timestamp.

Responses​

Connection status

application/json
JSON
{
  
"connected": true,
  
"username": "string",
  
"lastSyncAt": "string",
  
"error": "string"
}

Samples​

Trigger Hardcover sync​

POST
/api/hardcover/sync

Enqueue a job to synchronize reading progress and ratings with the Hardcover service. Requires a configured Hardcover credential.

Responses​

Sync job enqueued

application/json
JSON
{
  
"message": "string"
}

Samples​

List Hardcover sync log entries​

GET
/api/hardcover/sync/log

Return recent Hardcover sync log entries joined with book titles, sorted by last synced timestamp descending.

Parameters​

Query Parameters

limit
Type
integer
Default
20
Minimum
1
Maximum
100

Responses​

Array of sync log entries

application/json
JSON
[
  
{
  
  
"bookId": "string",
  
  
"bookTitle": "string",
  
  
"status": "string",
  
  
"progress": "string",
  
  
"rating": "string",
  
  
"syncedAt": "string"
  
}
]

Samples​

health​

Operations​

GET/api/health

Health check​

GET
/api/health

Returns minimal status for unauthenticated requests. Provide a valid API key for detailed check info.

Responses​

All systems healthy

application/json
JSON
{
  
"status": "string",
  
"service": "string",
  
"checks": {
  
  
"database": {
  
  
  
"status": "string",
  
  
  
"latencyMs": 0,
  
  
  
"error": "string"
  
  
},
  
  
"redis": {
  
  
  
"status": "string",
  
  
  
"latencyMs": 0,
  
  
  
"error": "string"
  
  
}
  
}
}

Samples​

Get inbox book​

GET
/api/inbox/{id}

Retrieve a single inbox/review book with its files and metadata candidates

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Book with files and candidates

application/json
JSON
{
  
"id": "string",
  
"status": "string",
  
"title": "string",
  
"author": "string",
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string",
  
"possibleDuplicate": {
  
  
"id": "string",
  
  
"title": "string",
  
  
"author": "string",
  
  
"status": "string"
  
},
  
"files": [
  
  
{
  
  
  
"id": "string",
  
  
  
"format": "string",
  
  
  
"originalName": "string",
  
  
  
"fileSize": "string"
  
  
}
  
],
  
"candidates": [
  
  
{
  
  
  
"id": "string",
  
  
  
"source": "string",
  
  
  
"normalized": {
  
  
  
},
  
  
  
"confidence": "string",
  
  
  
"selectedFields": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
]
}

Samples​

Get inbox book cover image​

GET
/api/inbox/{id}/cover

Extract and stream the embedded cover image from an inbox/review EPUB file

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Cover image (JPEG, PNG, WebP, or GIF)

image/*

Samples​

Rescan inbox book metadata​

PATCH
/api/inbox/{id}/rescan

Delete existing metadata candidates and re-fetch from external sources

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Rescan enqueued

application/json
JSON
{
  
"status": "string",
  
"bookId": "string",
  
"searchQuery": "string"
}

Samples​

Get inbox count​

GET
/api/inbox/count

Returns the number of books in inbox or review status

Responses​

Inbox count

application/json
JSON
{
  
"count": 0
}

Samples​

List inbox books​

GET
/api/inbox

Paginated list of books in inbox or review status

Parameters​

Query Parameters

page
Type
integer
Default
1
limit
Type
integer
Default
20
Maximum
100
q

Search title, author, or description

Type
string
sort

Sort order for results

Type
string
Valid values
"title_asc""title_desc""detected_newest""detected_oldest""status_asc""status_desc"
Default
"detected_newest"

Responses​

Paginated list of inbox books with files

application/json
JSON
{
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"createdAt": "string",
  
  
  
"files": [
  
  
  
  
{
  
  
  
  
  
"id": "string",
  
  
  
  
  
"format": "string",
  
  
  
  
  
"originalName": "string",
  
  
  
  
  
"fileSize": "string"
  
  
  
  
}
  
  
  
]
  
  
}
  
],
  
"pagination": {
  
  
"page": 0,
  
  
"limit": 0,
  
  
"total": 0,
  
  
"totalPages": 0
  
}
}

Samples​

Inbox processing status​

GET
/api/inbox/processing

Returns the current pipeline stage for books being processed (parsing, fetching metadata, organizing)

Responses​

Map of bookId to processing stage

application/json
JSON
{
  
"processing": {
  
  
"additionalProperties": {
  
  
  
"stage": "string",
  
  
  
"label": "string"
  
  
}
  
}
}

Samples​

Upload book files to inbox​

POST
/api/inbox/upload

Upload one or more book files via multipart/form-data. Supported formats: epub, pdf, mobi, azw3, cbz, cbr. Max 100MB per file.

Request Body​

multipart/form-data
object
string[]

Responses​

Files uploaded successfully

application/json
JSON
{
  
"uploaded": [
  
  
{
  
  
  
"filename": "string",
  
  
  
"size": 0
  
  
}
  
],
  
"errors": [
  
  
{
  
  
  
"filename": "string",
  
  
  
"error": "string"
  
  
}
  
]
}

Samples​

Retry a failed job​

POST
/api/jobs/{id}/retry

Retry a specific failed job by ID. Searches all queues for the job.

Parameters​

Path Parameters

id*

Job ID to retry

Type
string
Required

Responses​

Job retried successfully

application/json
JSON
{
  
"success": true,
  
"jobId": "string",
  
"queueName": "string"
}

Samples​

List failed jobs​

GET
/api/jobs/failed

Return failed jobs across all queues with job ID, queue name, error message, timestamps, and attempt count

Responses​

List of failed jobs

application/json
JSON
{
  
"jobs": [
  
  
{
  
  
  
"id": "string",
  
  
  
"queueName": "string",
  
  
  
"name": "string",
  
  
  
"data": {
  
  
  
},
  
  
  
"error": "string",
  
  
  
"failedAt": 0,
  
  
  
"attemptsMade": 0,
  
  
  
"maxAttempts": 0
  
  
}
  
],
  
"total": 0
}

Samples​

Job queue status​

GET
/api/jobs/status

Return job counts per queue (waiting, active, completed, failed, delayed, paused)

Responses​

Queue status counts

application/json
JSON
{
  
"queues": {
  
  
"additionalProperties": {
  
  
  
"waiting": 0,
  
  
  
"active": 0,
  
  
  
"completed": 0,
  
  
  
"failed": 0,
  
  
  
"delayed": 0,
  
  
  
"paused": 0
  
  
}
  
}
}

Samples​

Get library book​

GET
/api/library/{id}

Retrieve a single organized book with its files

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Book with files

application/json
JSON
{
  
"id": "string",
  
"status": "string",
  
"title": "string",
  
"author": "string",
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string",
  
"files": [
  
  
{
  
  
  
"id": "string",
  
  
  
"format": "string",
  
  
  
"originalName": "string",
  
  
  
"storagePath": "string",
  
  
  
"fileSize": "string",
  
  
  
"checksum": "string"
  
  
}
  
]
}

Samples​

Update library book​

PATCH
/api/library/{id}

Edit metadata fields on an organized book

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
  
"title": "string",
  
"author": "string",
  
"isbn10": "string",
  
"isbn13": "string",
  
"publisher": "string",
  
"publishedYear": 0,
  
"language": "string",
  
"description": "string",
  
"pageCount": 0,
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
]
}

Responses​

Updated book

application/json
JSON
{
  
"id": "string",
  
"status": "string",
  
"title": "string",
  
"author": "string",
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Samples​

Apply refetched metadata to a library book​

POST
/api/library/{id}/apply-metadata

Select metadata fields from refetched candidates and apply them to an organized book. Automatically enqueues a re-organize job to update file paths and re-embed EPUB metadata.

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
  
"fields": {
  
  
"additionalProperties": {
  
  
  
"source": "string",
  
  
  
"value": {
  
  
  
}
  
  
}
  
}
}

Responses​

Metadata applied and re-organize job enqueued

application/json
JSON
{
  
"id": "string",
  
"status": "string",
  
"title": "string",
  
"author": "string",
  
"genres": [
  
  
"string"
  
],
  
"tags": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Samples​

Get book cover image​

GET
/api/library/{id}/cover

Stream the cover image for an organized book

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Cover image (JPEG, PNG, WebP, or GIF)

image/*

Samples​

Download book file​

GET
/api/library/{id}/download/{fileId}

Download a specific file (EPUB, PDF, etc.) belonging to an organized book

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"
fileId*
Type
string
Required
Format
"uuid"

Responses​

File download with Content-Disposition header

application/octet-stream

Samples​

Get reading progress for a book​

GET
/api/library/{id}/progress

Returns reading progress across all devices by matching book file content hashes to KoReader document identifiers

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Reading progress entries for the book

application/json
JSON
{
  
"bookId": "string",
  
"progress": [
  
  
{
  
  
  
"document": "string",
  
  
  
"device": "string",
  
  
  
"deviceId": "string",
  
  
  
"progress": "string",
  
  
  
"percentage": 0,
  
  
  
"timestamp": 0
  
  
}
  
]
}

Samples​

Refetch metadata from external sources​

POST
/api/library/{id}/refetch

Delete existing non-file metadata candidates and re-fetch from external sources (Google Books, Hardcover) for an organized book. The book stays organized throughout.

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Refetch enqueued

application/json
JSON
{
  
"status": "string",
  
"bookId": "string",
  
"searchQuery": "string"
}

Samples​

Re-organize a library book​

POST
/api/library/{id}/reorganize

Enqueue a BOOK_ORGANIZE job for an already-organized book so its files are moved to match updated metadata (author/title)

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Reorganize job enqueued

application/json
JSON
{
  
"message": "string",
  
"bookId": "string"
}

Samples​

Get library filter facets​

GET
/api/library/facets

Returns distinct authors and genres from organized books for filter dropdowns

Responses​

Distinct authors and genres

application/json
JSON
{
  
"authors": [
  
  
"string"
  
],
  
"genres": [
  
  
"string"
  
]
}

Samples​

List library books​

GET
/api/library

Paginated list of organized books with optional search and filtering

Parameters​

Query Parameters

page
Type
integer
Default
1
limit
Type
integer
Default
20
Maximum
100
author

Filter by author (partial match)

Type
string
genre

Filter by genre (exact, case-insensitive)

Type
string
q

Full-text search across title, author, and description with typo tolerance

Type
string
sort

Sort order for results

Type
string
Valid values
"title_asc""title_desc""author_asc""author_desc""added_newest""added_oldest"
Default
"title_asc"

Responses​

Paginated list of books with files

application/json
JSON
{
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"createdAt": "string",
  
  
  
"files": [
  
  
  
  
{
  
  
  
  
  
"id": "string",
  
  
  
  
  
"format": "string",
  
  
  
  
  
"originalName": "string",
  
  
  
  
  
"fileSize": "string"
  
  
  
  
}
  
  
  
]
  
  
}
  
],
  
"pagination": {
  
  
"page": 0,
  
  
"limit": 0,
  
  
"total": 0,
  
  
"totalPages": 0
  
}
}

Samples​

List books by reading status​

GET
/api/reading-status/{status}

Returns a paginated list of organized books filtered by the given reading status, with optional search and sorting.

Parameters​

Path Parameters

status*

Reading status to filter by

Type
string
Required
Valid values
"unread""reading""finished""paused"

Query Parameters

page

Page number (1-based)

Type
integer
Default
1
perPage

Number of items per page

Type
integer
Default
20
Maximum
100
sort

Sort field

Type
string
Valid values
"title""author""percentage""lastRead"
Default
"title"
order

Sort direction

Type
string
Valid values
"asc""desc"
Default
"asc"
search

Full-text search query

Type
string

Responses​

Paginated list of books with reading progress

application/json
JSON
{
  
"books": [
  
  
{
  
  
  
"id": "string",
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"coverPath": "string",
  
  
  
"genres": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"pageCount": 0,
  
  
  
"percentage": 0,
  
  
  
"device": "string",
  
  
  
"lastReadAt": "string",
  
  
  
"readingStatus": "string"
  
  
}
  
],
  
"total": 0,
  
"page": 0,
  
"perPage": 0
}

Samples​

Get reading status counts​

GET
/api/reading-status/counts

Returns the count of organized books in each reading status (unread, reading, finished, paused).

Responses​

Status counts

application/json
JSON
{
  
"unread": 0,
  
"reading": 0,
  
"finished": 0,
  
"paused": 0
}

Samples​

search​

Operations​

GET/api/search/suggest

Search suggestions for command palette​

GET
/api/search/suggest

Lightweight prefix search returning up to 8 results for autocomplete. Searches both organized and review books.

Parameters​

Query Parameters

q*

Search prefix

Type
string
Required

Responses​

Search suggestions

application/json
JSON
{
  
"data": [
  
  
{
  
  
  
"id": 0,
  
  
  
"title": "string",
  
  
  
"author": "string",
  
  
  
"status": "string",
  
  
  
"coverUrl": "string"
  
  
}
  
]
}

Samples​

settings​

Operations​

GET/api/settingsPATCH/api/settings

Get settings​

GET
/api/settings

Return current library and inbox path settings

Responses​

Current settings

application/json
JSON
{
  
"libraryPath": "string",
  
"inboxPath": "string",
  
"kosyncConfigured": true
}

Samples​

Update settings​

PATCH
/api/settings

Request Body​

application/json
JSON
{
  
"libraryPath": "string",
  
"inboxPath": "string"
}

Responses​

Settings updated

application/json
JSON
{
  
"updated": [
  
  
"string"
  
],
  
"persistent": true,
  
"settings": {
  
  
"libraryPath": "string",
  
  
"inboxPath": "string"
  
}
}

Samples​

stats​

Operations​

GET/api/stats

Get reading statistics​

GET
/api/stats

Returns reading analytics: books finished, daily activity, genre distribution, reading streak, average finish time

Responses​

Reading statistics

application/json
JSON
{
  
"booksFinished": {
  
  
"allTime": 0,
  
  
"thisYear": 0,
  
  
"thisMonth": 0
  
},
  
"dailyActivity": [
  
  
{
  
  
  
"day": "string",
  
  
  
"pagesRead": 0,
  
  
  
"sessions": 0
  
  
}
  
],
  
"genreDistribution": [
  
  
{
  
  
  
"genre": "string",
  
  
  
"count": 0
  
  
}
  
],
  
"streak": {
  
  
"current": 0,
  
  
"longest": 0
  
},
  
"avgDaysToFinish": 0
}

Samples​

Get reading progress​

GET
/kosync/syncs/progress/{document}

Get the most recent reading progress for a document. The document identifier is the MD5 hash of the book file, as computed by KOReader.

Parameters​

Path Parameters

document*

MD5 hash of the book file

Type
string
Required

Responses​

Reading progress for the document

application/json
JSON
{
  
"document": "string",
  
"progress": "string",
  
"percentage": 0,
  
"device": "string",
  
"device_id": "string",
  
"timestamp": 0
}

Samples​

Update reading progress​

PUT
/kosync/syncs/progress

Create or update reading progress for a document on a device. Upserts on (document, device) and appends to reading history.

Request Body​

application/json
JSON
{
  
"document": "string",
  
"progress": "string",
  
"device": "string",
  
"percentage": 0,
  
"device_id": "string"
}

Responses​

Progress saved

application/json
JSON
{
  
"document": "string",
  
"progress": "string",
  
"percentage": 0,
  
"device": "string",
  
"device_id": "string",
  
"timestamp": 0
}

Samples​

Authenticate KoSync user​

POST
/kosync/users/auth

Authenticate a KOReader device for reading progress sync. Validates against configured KoSync credentials.

Request Body​

application/json
JSON
{
  
"username": "string",
  
"password": "string"
}

Responses​

Authentication successful

application/json
JSON
{
  
"authorized": "string"
}

Samples​

Register KoSync user​

POST
/kosync/users/create

KOReader calls this to register a new user. Registration is disabled — credentials must be configured via environment variables or the settings UI.

Request Body​

application/json
JSON
{
  
"username": "string",
  
"password": "string"
}

Responses​

Registration disabled

Samples​

OPDS books by author​

GET
/opds/authors/{slug}

Acquisition feed of books by a specific author, matched by slug

Parameters​

Path Parameters

slug*
Type
string
Required

Query Parameters

page
Type
integer
Default
1

Responses​

OPDS acquisition feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS single book entry​

GET
/opds/books/{id}

Single book entry with per-format acquisition links and cover image

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

OPDS entry document (Atom XML)

application/atom+xml
XML

Samples​

OPDS all books feed​

GET
/opds/books

Paginated acquisition feed of all organized books, ordered by title

Parameters​

Query Parameters

page
Type
integer
Default
1

Responses​

OPDS acquisition feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS cover image​

GET
/opds/covers/{id}

Stream cover image for a book (for OPDS clients)

Parameters​

Path Parameters

id*
Type
string
Required
Format
"uuid"

Responses​

Cover image (JPEG, PNG, WebP, or GIF)

image/*

Samples​

OPDS file download​

GET
/opds/download/{fileId}

Download a book file directly by file ID (for OPDS clients)

Parameters​

Path Parameters

fileId*
Type
string
Required
Format
"uuid"

Responses​

File download with Content-Disposition header

application/octet-stream

Samples​

OPDS books by genre​

GET
/opds/genres/{slug}

Acquisition feed of books matching a specific genre, matched by slug

Parameters​

Path Parameters

slug*
Type
string
Required

Query Parameters

page
Type
integer
Default
1

Responses​

OPDS acquisition feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS genres navigation feed​

GET
/opds/genres

Navigation feed listing all distinct genres with book counts

Responses​

OPDS navigation feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS catalog root​

GET
/opds

Root navigation feed for OPDS-compatible readers

Responses​

OPDS navigation feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS new arrivals feed​

GET
/opds/new

Acquisition feed of recently added books, ordered by creation date

Parameters​

Query Parameters

page
Type
integer
Default
1

Responses​

OPDS acquisition feed (Atom XML)

application/atom+xml
XML

Samples​

OPDS search​

GET
/opds/search

Returns an OpenSearch description document (no query), or a search results acquisition feed (?q=term)

Parameters​

Query Parameters

q

Search query

Type
string
page
Type
integer
Default
1

Responses​

OpenSearch description or OPDS acquisition feed (Atom XML)

application/atom+xml
XML

Samples​

Powered by VitePress OpenAPI