API docs by Redocly

Librarium API (26.4.0)

Download OpenAPI specification:

URL: https://github.com/fireball1725/librarium License: AGPL-3.0 Terms of Service

Self-hosted library tracking API. All protected endpoints require a Bearer JWT in the Authorization header.

admin

List AI providers (admin)

Returns provider status, masked config, active flag, and config-field schema for each registered AI provider.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set the active AI provider (admin)

Exactly one AI provider is active at a time. Passing an empty name disables AI suggestions.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Provider name

provider
string

Responses

Request samples

Content type
application/json
{
  • "provider": "string"
}

Get AI data-access permissions (admin)

Returns the deployment-wide data categories the AI may access. Combined restrictive-wins with each user's opt-in.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "favourites": true,
  • "full_library": true,
  • "ratings": true,
  • "reading_history": true,
  • "taste_profile": true
}

Update AI data-access permissions (admin)

Replaces the deployment-wide data-access policy. All fields must be provided; omitted fields default to false.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Permissions object

favourites
boolean
full_library
boolean
ratings
boolean
reading_history
boolean
taste_profile
boolean

Responses

Request samples

Content type
application/json
{
  • "favourites": true,
  • "full_library": true,
  • "ratings": true,
  • "reading_history": true,
  • "taste_profile": true
}

Configure an AI provider (admin)

Updates the API key, model, base URL, or enabled flag for the named provider. Secrets are merged over existing config so omitted keys are preserved.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Provider name

Request Body schema: application/json
required

Provider configuration key-value pairs

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Test an AI provider (admin)

Performs a cheap probe call to verify the provider's API key and model.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "ok": true,
  • "reply": "string"
}

List configurable jobs (admin)

Returns a summary of every admin-configurable scheduled job.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get AI suggestions job config (admin)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Update AI suggestions job config (admin)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Job config

enabled
boolean
include_taste_profile
boolean
interval_minutes
integer
max_buy_per_user
integer
max_read_next_per_user
integer
max_tokens_backfill
integer

MaxTokensBackfill applies to each backfill retry prompt. Smaller than initial since backfill only asks for the remaining slots.

max_tokens_initial
integer

MaxTokensInitial is the cap on output tokens for the first pass. Thinking models (qwen3, deepseek-r1, extended-thinking Claude) burn through many tokens reasoning before emitting anything — too low a cap leaves the response empty.

user_run_rate_limit_per_day
integer

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Trigger a suggestions run for every opted-in user (admin)

Enqueues a job per opted-in user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enqueued": 0
}

List recent AI suggestion runs across all users (admin)

Returns the most recent suggestion runs with cost, status, and owning user. Used by the admin jobs page.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete all finished AI suggestion runs (admin)

Removes every run in a terminal state (completed, failed, cancelled). Running runs are left alone.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "deleted": 0
}

Get any AI suggestion run (admin)

Returns the run metadata plus every pipeline event. Admin can view any user's run.

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "run": {
    }
}

Cancel a running AI suggestion run (admin)

Marks a running run as cancelled; the worker checks status between stages and exits on the next check. Completed or already-cancelled runs return 404.

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

List metadata providers (admin)

Returns the status and configuration of all registered metadata providers.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get provider priority order (admin)

Returns the ordered list of provider names used when merging results.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "order": [
    ]
}

Set provider priority order (admin)

Sets the ordered list of provider names used when merging results.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Ordered provider names

order
Array of strings

Responses

Request samples

Content type
application/json
{
  • "order": [
    ]
}

Configure a metadata provider (admin)

Updates the API key or settings for the named provider.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Request Body schema: application/json
required

Provider configuration key-value pairs

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Test a metadata provider (admin)

Performs a live test lookup to verify provider credentials are working.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "title": "string"
}

List all users (admin)

Returns a paginated list of all instance users. Instance admin only.

Authorizations:
BearerAuth
query Parameters
page
integer

Page number (default 1)

per_page
integer

Items per page (default 20, max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "per_page": 0,
  • "total": 0
}

Create a user (admin)

Creates a new user account bypassing registration settings. Instance admin only.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Create user request

display_name
string
email
string
password
string
username
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "display_name": "string",
  • "email": "string",
  • "id": "string",
  • "is_active": true,
  • "is_instance_admin": true,
  • "last_login_at": "string",
  • "username": "string"
}

Delete a user (admin)

Permanently deletes a user account. Instance admin only. Cannot delete yourself.

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Update a user (admin)

Partially updates a user's profile or admin/active status. Instance admin only.

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Request Body schema: application/json

Fields to update

display_name
string
email
string
is_active
boolean
is_instance_admin
boolean

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "is_active": true,
  • "is_instance_admin": true
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "display_name": "string",
  • "email": "string",
  • "id": "string",
  • "is_active": true,
  • "is_instance_admin": true,
  • "last_login_at": "string",
  • "username": "string"
}

ai

List AI providers (admin)

Returns provider status, masked config, active flag, and config-field schema for each registered AI provider.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set the active AI provider (admin)

Exactly one AI provider is active at a time. Passing an empty name disables AI suggestions.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Provider name

provider
string

Responses

Request samples

Content type
application/json
{
  • "provider": "string"
}

Get AI data-access permissions (admin)

Returns the deployment-wide data categories the AI may access. Combined restrictive-wins with each user's opt-in.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "favourites": true,
  • "full_library": true,
  • "ratings": true,
  • "reading_history": true,
  • "taste_profile": true
}

Update AI data-access permissions (admin)

Replaces the deployment-wide data-access policy. All fields must be provided; omitted fields default to false.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Permissions object

favourites
boolean
full_library
boolean
ratings
boolean
reading_history
boolean
taste_profile
boolean

Responses

Request samples

Content type
application/json
{
  • "favourites": true,
  • "full_library": true,
  • "ratings": true,
  • "reading_history": true,
  • "taste_profile": true
}

Configure an AI provider (admin)

Updates the API key, model, base URL, or enabled flag for the named provider. Secrets are merged over existing config so omitted keys are preserved.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Provider name

Request Body schema: application/json
required

Provider configuration key-value pairs

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Test an AI provider (admin)

Performs a cheap probe call to verify the provider's API key and model.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "ok": true,
  • "reply": "string"
}

Get my AI preferences

Returns whether the caller has opted in to AI features.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "opt_in": true
}

Update my AI preferences

Sets whether the caller is opted in to AI features.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Opt-in flag

opt_in
boolean

Responses

Request samples

Content type
application/json
{
  • "opt_in": true
}

Response samples

Content type
application/json
{
  • "opt_in": true
}

List my AI suggestions

Returns the current AI-generated recommendations for the caller. Filter by type (buy | read_next) and status.

Authorizations:
BearerAuth
query Parameters
type
string

Filter by type: buy | read_next

status
string

Filter by status: new | dismissed | interested | added_to_library

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get my AI suggestion run quota

Returns how many suggestion runs the caller has used in the last 24h and the configured per-user daily limit.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "resets_at": "string",
  • "unlimited": true,
  • "used": 0
}

Trigger a suggestions run for the caller

Enqueues a background job to regenerate suggestions. Rate-limited by admin config.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

List my recent AI suggestion runs

Returns the caller's most recent suggestion runs with cost and status. Newest first.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get one of my AI suggestion runs

Returns the run metadata plus every pipeline event emitted during execution (prompt, AI responses, enrichment decisions, read_next matches, backfill passes).

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "run": {
    }
}

Block a suggestion so it never reappears

Creates a persistent block scoped to the book, the author, or the series.

Authorizations:
BearerAuth
path Parameters
id
required
string

Suggestion ID

Request Body schema: application/json
required

Block scope: book | author | series

scope
string

Responses

Request samples

Content type
application/json
{
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Update a suggestion's status

Mark a suggestion as dismissed, interested, or added_to_library.

Authorizations:
BearerAuth
path Parameters
id
required
string

Suggestion ID

Request Body schema: application/json
required

New status

status
string

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Get my taste profile

Returns the JSON taste profile the user has saved. Empty object if none saved.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{ }

Update my taste profile

Replaces the saved taste profile with the supplied JSON object.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Taste profile JSON object

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

jobs

List configurable jobs (admin)

Returns a summary of every admin-configurable scheduled job.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get AI suggestions job config (admin)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Update AI suggestions job config (admin)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Job config

enabled
boolean
include_taste_profile
boolean
interval_minutes
integer
max_buy_per_user
integer
max_read_next_per_user
integer
max_tokens_backfill
integer

MaxTokensBackfill applies to each backfill retry prompt. Smaller than initial since backfill only asks for the remaining slots.

max_tokens_initial
integer

MaxTokensInitial is the cap on output tokens for the first pass. Thinking models (qwen3, deepseek-r1, extended-thinking Claude) burn through many tokens reasoning before emitting anything — too low a cap leaves the response empty.

user_run_rate_limit_per_day
integer

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "include_taste_profile": true,
  • "interval_minutes": 0,
  • "max_buy_per_user": 0,
  • "max_read_next_per_user": 0,
  • "max_tokens_backfill": 0,
  • "max_tokens_initial": 0,
  • "user_run_rate_limit_per_day": 0
}

Trigger a suggestions run for every opted-in user (admin)

Enqueues a job per opted-in user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enqueued": 0
}

List recent AI suggestion runs across all users (admin)

Returns the most recent suggestion runs with cost, status, and owning user. Used by the admin jobs page.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete all finished AI suggestion runs (admin)

Removes every run in a terminal state (completed, failed, cancelled). Running runs are left alone.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "deleted": 0
}

Get any AI suggestion run (admin)

Returns the run metadata plus every pipeline event. Admin can view any user's run.

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "run": {
    }
}

Cancel a running AI suggestion run (admin)

Marks a running run as cancelled; the worker checks status between stages and exits on the next check. Completed or already-cancelled runs return 404.

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

providers

List metadata providers (admin)

Returns the status and configuration of all registered metadata providers.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get provider priority order (admin)

Returns the ordered list of provider names used when merging results.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "order": [
    ]
}

Set provider priority order (admin)

Sets the ordered list of provider names used when merging results.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Ordered provider names

order
Array of strings

Responses

Request samples

Content type
application/json
{
  • "order": [
    ]
}

Configure a metadata provider (admin)

Updates the API key or settings for the named provider.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Request Body schema: application/json
required

Provider configuration key-value pairs

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Test a metadata provider (admin)

Performs a live test lookup to verify provider credentials are working.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "title": "string"
}

auth

Log in

Authenticates with username/email and password; returns tokens.

Request Body schema: application/json
required

Login request

identifier
string
password
string

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "user": {
    }
}

Log out

Revokes the current access token. No request body needed.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get current user

Returns the profile of the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "id": "string",
  • "is_instance_admin": true,
  • "username": "string"
}

Update current user profile

Updates the display name and email of the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Update profile request

display_name
string
email
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "id": "string",
  • "is_instance_admin": true,
  • "username": "string"
}

Change password

Changes the password for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Change password request

current_password
string
new_password
string

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get user preferences

Returns the stored preferences key-value map for the current user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "prefs": { }
}

Patch user preferences

Merges supplied key-value pairs into the stored preferences.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Arbitrary key-value pairs to merge

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "string"
}

Refresh access token

Exchanges a valid refresh token for a new token pair.

Request Body schema: application/json
required

Refresh request

refresh_token
string

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "user": {
    }
}

Register a new user

Creates a new user account. Registration may be disabled by instance config.

Request Body schema: application/json
required

Registration request

display_name
string
email
string
password
string
username
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "user": {
    }
}

Search users

Full-text search across users; returns minimal profile data. Query must be at least 2 characters.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query (min 2 chars)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

books

Search contributors

Full-text search for contributors (authors, illustrators, etc.). Query must be at least 2 characters.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query (min 2 chars)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a contributor

Creates a new contributor record (author, illustrator, etc.).

Authorizations:
BearerAuth
Request Body schema: application/json
required

Contributor name

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Find book by ISBN

Searches the library for a book with the given ISBN.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

isbn
required
string

ISBN-10 or ISBN-13

Responses

Response samples

Content type
application/json
{
  • "added_by": "string",
  • "contributors": [
    ],
  • "cover_url": "string",
  • "created_at": "string",
  • "description": "string",
  • "genres": [
    ],
  • "id": "string",
  • "language": "string",
  • "library_id": "string",
  • "media_type": "string",
  • "media_type_id": "string",
  • "publish_year": 0,
  • "publisher": "string",
  • "series": [
    ],
  • "shelves": [
    ],
  • "subtitle": "string",
  • "tags": [
    ],
  • "title": "string",
  • "updated_at": "string"
}

List books in a library

Returns a paginated, filtered, sorted list of books in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
q
string

Search query or query-language expression

page
integer

Page number

per_page
integer

Items per page

sort
string

Sort field

sort_dir
string

Sort direction (asc/desc)

letter
string

Filter by first letter

tag
string

Filter by tag name

type_filter
string

Filter by media type

regex
boolean

Treat q as regex

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "per_page": 0,
  • "total": 0
}

Create a book

Adds a new book to the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Book details

contributors
Array of objects
description
string
edition
object
genre_ids
Array of strings
media_type_id
string
subtitle
string
tag_ids
Array of strings
title
string

Responses

Request samples

Content type
application/json
{
  • "contributors": [
    ],
  • "description": "string",
  • "edition": { },
  • "genre_ids": [
    ],
  • "media_type_id": "string",
  • "subtitle": "string",
  • "tag_ids": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "added_by": "string",
  • "contributors": [
    ],
  • "cover_url": "string",
  • "created_at": "string",
  • "description": "string",
  • "genres": [
    ],
  • "id": "string",
  • "language": "string",
  • "library_id": "string",
  • "media_type": "string",
  • "media_type_id": "string",
  • "publish_year": 0,
  • "publisher": "string",
  • "series": [
    ],
  • "shelves": [
    ],
  • "subtitle": "string",
  • "tags": [
    ],
  • "title": "string",
  • "updated_at": "string"
}

Bulk refresh covers

Creates an enrichment batch to refresh cover images for a list of books.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Books to refresh covers for

book_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "book_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "created_at": "string",
  • "created_by": "string",
  • "failed_books": 0,
  • "force": true,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "processed_books": 0,
  • "skipped_books": 0,
  • "status": "pending",
  • "total_books": 0,
  • "type": "metadata",
  • "updated_at": "string"
}

Bulk enrich books

Creates an enrichment batch to refresh metadata for a list of books.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Books to enrich

book_ids
Array of strings
force
boolean

Responses

Request samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "force": true
}

Response samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "created_at": "string",
  • "created_by": "string",
  • "failed_books": 0,
  • "force": true,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "processed_books": 0,
  • "skipped_books": 0,
  • "status": "pending",
  • "total_books": 0,
  • "type": "metadata",
  • "updated_at": "string"
}

Get books collection fingerprint

Returns a cheap summary (count + max updated_at) that clients can compare against a stored value to decide whether to resync.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
{
  • "max_updated_at": "string",
  • "total": 0
}

List available first letters

Returns the sorted list of first letters (by sort title) that have books in this library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a book

Returns full details for a specific book including contributors, tags, genres, and series.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Response samples

Content type
application/json
{
  • "added_by": "string",
  • "contributors": [
    ],
  • "cover_url": "string",
  • "created_at": "string",
  • "description": "string",
  • "genres": [
    ],
  • "id": "string",
  • "language": "string",
  • "library_id": "string",
  • "media_type": "string",
  • "media_type_id": "string",
  • "publish_year": 0,
  • "publisher": "string",
  • "series": [
    ],
  • "shelves": [
    ],
  • "subtitle": "string",
  • "tags": [
    ],
  • "title": "string",
  • "updated_at": "string"
}

Update a book

Replaces the book's metadata.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Request Body schema: application/json
required

Updated book

contributors
Array of objects
description
string
genre_ids
Array of strings
media_type_id
string
subtitle
string
tag_ids
Array of strings
title
string

Responses

Request samples

Content type
application/json
{
  • "contributors": [
    ],
  • "description": "string",
  • "genre_ids": [
    ],
  • "media_type_id": "string",
  • "subtitle": "string",
  • "tag_ids": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "added_by": "string",
  • "contributors": [
    ],
  • "cover_url": "string",
  • "created_at": "string",
  • "description": "string",
  • "genres": [
    ],
  • "id": "string",
  • "language": "string",
  • "library_id": "string",
  • "media_type": "string",
  • "media_type_id": "string",
  • "publish_year": 0,
  • "publisher": "string",
  • "series": [
    ],
  • "shelves": [
    ],
  • "subtitle": "string",
  • "tags": [
    ],
  • "title": "string",
  • "updated_at": "string"
}

Delete a book

Permanently deletes a book and all its editions from the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

contributors

Delete a contributor

Hard-deletes a contributor. Returns 409 if they still have books.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Responses

Update a contributor's profile fields

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Request Body schema: application/json
required

Payload (all fields optional)

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Apply metadata to a contributor

Writes provider-sourced fields and bibliography to the contributor record.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Request Body schema: application/json
required

Metadata payload

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Fetch contributor metadata from a provider

Fetches full profile + bibliography from a specific provider without persisting.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

query Parameters
provider
required
string

Provider name

external_id
required
string

Provider-specific ID

Responses

Response samples

Content type
application/json
{ }

Serve contributor photo

Streams the primary photo for a contributor.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Responses

Upload contributor photo

Accepts a multipart form upload and stores it as the contributor's primary photo.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Request Body schema: multipart/form-data
required
photo
required
string <binary>

Photo file

Responses

Delete contributor photo

Removes the primary photo for a contributor.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

Responses

Delete a contributor work

Soft-deletes a bibliography entry for a contributor.

Authorizations:
BearerAuth
path Parameters
contributor_id
required
string

Contributor UUID

work_id
required
string

Work UUID

Responses

List contributors for a library (paged)

Returns a paginated, filtered, sorted list of contributors.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
q
string

Name filter

letter
string

First-letter filter

sort
string

Sort field: name|book_count

sort_dir
string

Sort direction: asc|desc

page
integer

Page number

per_page
integer

Items per page

Responses

Response samples

Content type
application/json
{ }

Get available first letters for contributors in a library

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a contributor with works

Returns full contributor profile and bibliography, annotated with library context.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

contributor_id
required
string

Contributor UUID

Responses

Response samples

Content type
application/json
{ }

Search external providers for contributors

Queries enabled ContributorProviders for name candidates.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query

Responses

Response samples

Content type
application/json
[
  • { }
]

enrichment

List enrichment batches

Returns all enrichment batches for the calling user across all libraries.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete all finished enrichment batches

Bulk-deletes all done/failed/cancelled enrichment batches for the calling user.

Authorizations:
BearerAuth

Responses

Get an enrichment batch

Returns a specific enrichment batch with its per-book items.

Authorizations:
BearerAuth
path Parameters
batch_id
required
string

Batch UUID

Responses

Response samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "created_at": "string",
  • "created_by": "string",
  • "failed_books": 0,
  • "force": true,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "processed_books": 0,
  • "skipped_books": 0,
  • "status": "pending",
  • "total_books": 0,
  • "type": "metadata",
  • "updated_at": "string"
}

Delete an enrichment batch

Deletes a finished enrichment batch record.

Authorizations:
BearerAuth
path Parameters
batch_id
required
string

Batch UUID

Responses

Cancel an enrichment batch

Requests cancellation of a running enrichment batch.

Authorizations:
BearerAuth
path Parameters
batch_id
required
string

Batch UUID

Responses

Bulk enrich books

Creates an enrichment batch to refresh metadata for a list of books.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Books to enrich

book_ids
Array of strings
force
boolean

Responses

Request samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "force": true
}

Response samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "created_at": "string",
  • "created_by": "string",
  • "failed_books": 0,
  • "force": true,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "processed_books": 0,
  • "skipped_books": 0,
  • "status": "pending",
  • "total_books": 0,
  • "type": "metadata",
  • "updated_at": "string"
}

genres

List genres

Returns all globally defined genres.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a genre (admin)

Creates a new global genre. Instance admin only.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Genre name

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string"
}

Update a genre (admin)

Updates the name of a global genre. Instance admin only.

Authorizations:
BearerAuth
path Parameters
genre_id
required
string

Genre UUID

Request Body schema: application/json
required

Updated name

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string"
}

Delete a genre (admin)

Permanently deletes a genre. Instance admin only.

Authorizations:
BearerAuth
path Parameters
genre_id
required
string

Genre UUID

Responses

health

Health check

Returns the API health status and current version

Responses

Response samples

Content type
application/json
{
  • "started_at": "string",
  • "status": "string",
  • "version": "string"
}

imports

List all import jobs (global)

Returns all import jobs across all libraries for the calling user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete all finished import jobs

Bulk-deletes all done/failed/cancelled import jobs for the calling user.

Authorizations:
BearerAuth

Responses

Delete an import job

Deletes a finished (done/failed/cancelled) import job record.

Authorizations:
BearerAuth
path Parameters
import_id
required
string

Import job UUID

Responses

Cancel an import job

Requests cancellation of a running import job.

Authorizations:
BearerAuth
path Parameters
import_id
required
string

Import job UUID

Responses

List import jobs for a library

Returns all import jobs for a specific library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a CSV import job

Accepts a multipart form upload with a CSV file and column mapping, and starts an import job.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: multipart/form-data
required
file
required
string <binary>

CSV file to import

mapping
string

JSON column mapping {field_name: column_index}

skip_duplicates
string

Skip duplicate ISBNs (default true)

default_format
string

Default edition format (default paperback)

enrich_metadata
string

Enrich metadata after import

enrich_covers
string

Fetch covers after import

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "failed_rows": 0,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "options": {
    },
  • "processed_rows": 0,
  • "skipped_rows": 0,
  • "status": "pending",
  • "total_rows": 0,
  • "updated_at": "string"
}

Get an import job

Returns the status and progress of a specific import job.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

import_id
required
string

Import job UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "failed_rows": 0,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "options": {
    },
  • "processed_rows": 0,
  • "skipped_rows": 0,
  • "status": "pending",
  • "total_rows": 0,
  • "updated_at": "string"
}

libraries

List libraries

Returns all libraries the authenticated user has access to.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a library

Creates a new library owned by the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Library details

description
string
is_public
boolean
name
string
slug
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "is_public": true,
  • "name": "string",
  • "slug": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "id": "string",
  • "is_public": true,
  • "name": "string",
  • "owner_id": "string",
  • "slug": "string",
  • "updated_at": "string"
}

Get a library

Returns details for a specific library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "id": "string",
  • "is_public": true,
  • "name": "string",
  • "owner_id": "string",
  • "slug": "string",
  • "updated_at": "string"
}

Update a library

Updates name, description, or visibility of a library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Updated fields

description
string
is_public
boolean
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "is_public": true,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "id": "string",
  • "is_public": true,
  • "name": "string",
  • "owner_id": "string",
  • "slug": "string",
  • "updated_at": "string"
}

Delete a library

Permanently deletes a library and all its contents.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

List library members

Returns all members of a library with their roles.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
search
string

Filter by username/display name

tag
string

Filter by tag name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a member to a library

Adds an existing user to the library with the specified role.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Member details

role
string
user_id
string

Responses

Request samples

Content type
application/json
{
  • "role": "string",
  • "user_id": "string"
}

Remove a member from a library

Removes a user's membership from a library. Cannot remove the owner.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

user_id
required
string

User UUID

Responses

Update a member's role

Changes the role of an existing library member.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

user_id
required
string

User UUID

Request Body schema: application/json
required

New role

role
string

Responses

Request samples

Content type
application/json
{
  • "role": "string"
}

covers

Bulk refresh covers

Creates an enrichment batch to refresh cover images for a list of books.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Books to refresh covers for

book_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "book_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_ids": [
    ],
  • "created_at": "string",
  • "created_by": "string",
  • "failed_books": 0,
  • "force": true,
  • "id": "string",
  • "items": [
    ],
  • "library_id": "string",
  • "library_name": "string",
  • "processed_books": 0,
  • "skipped_books": 0,
  • "status": "pending",
  • "total_books": 0,
  • "type": "metadata",
  • "updated_at": "string"
}

Serve book cover image

Streams the primary cover image for a book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Upload book cover

Accepts a multipart form upload and stores the image as the book's cover.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Request Body schema: multipart/form-data
required
cover
required
string <binary>

Cover image file

Responses

Delete book cover

Removes the cover image from a book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Fetch book cover from URL

Downloads a cover image from the given URL and stores it as the book's cover.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Request Body schema: application/json
required

Cover URL

url
string

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

editions

List editions of a book

Returns all editions (physical/digital/audio) for a book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an edition

Adds a new edition to an existing book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Request Body schema: application/json
required

Edition details

acquired_at
string
copy_count
integer
description
string
duration_seconds
integer
edition_name
string
format
string
is_primary
boolean
isbn_10
string
isbn_13
string
language
string
narrator
string
page_count
integer
publish_date
string
publisher
string

Responses

Request samples

Content type
application/json
{
  • "acquired_at": "string",
  • "copy_count": 0,
  • "description": "string",
  • "duration_seconds": 0,
  • "edition_name": "string",
  • "format": "string",
  • "is_primary": true,
  • "isbn_10": "string",
  • "isbn_13": "string",
  • "language": "string",
  • "narrator": "string",
  • "page_count": 0,
  • "publish_date": "string",
  • "publisher": "string"
}

Response samples

Content type
application/json
{
  • "acquired_at": "string",
  • "book_id": "string",
  • "copy_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "duration_seconds": 0,
  • "edition_name": "string",
  • "format": "string",
  • "id": "string",
  • "is_primary": true,
  • "isbn_10": "string",
  • "isbn_13": "string",
  • "language": "string",
  • "narrator": "string",
  • "page_count": 0,
  • "publish_date": "string",
  • "publisher": "string",
  • "updated_at": "string"
}

Update an edition

Replaces an edition's metadata.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Request Body schema: application/json
required

Edition details

acquired_at
string
copy_count
integer
description
string
duration_seconds
integer
edition_name
string
format
string
is_primary
boolean
isbn_10
string
isbn_13
string
language
string
narrator
string
page_count
integer
publish_date
string
publisher
string

Responses

Request samples

Content type
application/json
{
  • "acquired_at": "string",
  • "copy_count": 0,
  • "description": "string",
  • "duration_seconds": 0,
  • "edition_name": "string",
  • "format": "string",
  • "is_primary": true,
  • "isbn_10": "string",
  • "isbn_13": "string",
  • "language": "string",
  • "narrator": "string",
  • "page_count": 0,
  • "publish_date": "string",
  • "publisher": "string"
}

Response samples

Content type
application/json
{
  • "acquired_at": "string",
  • "book_id": "string",
  • "copy_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "duration_seconds": 0,
  • "edition_name": "string",
  • "format": "string",
  • "id": "string",
  • "is_primary": true,
  • "isbn_10": "string",
  • "isbn_13": "string",
  • "language": "string",
  • "narrator": "string",
  • "page_count": 0,
  • "publish_date": "string",
  • "publisher": "string",
  • "updated_at": "string"
}

Delete an edition

Permanently deletes an edition from a book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Responses

Upload edition file

Attaches an ebook or audiobook file to an edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Book file (epub, pdf, mp3, m4b, etc.)

Responses

Link existing file to edition

Links a file that already exists on the server (within a storage location) to an edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Responses

Download edition file

Streams a specific file attached to a digital edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

file_id
required
string

File UUID

Responses

Remove edition file

Removes a specific file from an edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

file_id
required
string

File UUID

Responses

Get my reading interaction

Returns the current user's reading status, rating, and notes for a specific edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Responses

Response samples

Content type
application/json
{
  • "book_edition_id": "string",
  • "created_at": "string",
  • "date_finished": "string",
  • "date_started": "string",
  • "id": "string",
  • "is_favorite": true,
  • "notes": "string",
  • "rating": 0,
  • "read_status": "string",
  • "reread_count": 0,
  • "review": "string",
  • "updated_at": "string",
  • "user_id": "string"
}

Set my reading interaction

Creates or updates the current user's reading status, rating, and notes for an edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Request Body schema: application/json
required

Interaction data

date_finished
string
date_started
string
is_favorite
boolean
notes
string
rating
integer
read_status
string
review
string

Responses

Request samples

Content type
application/json
{
  • "date_finished": "string",
  • "date_started": "string",
  • "is_favorite": true,
  • "notes": "string",
  • "rating": 0,
  • "read_status": "string",
  • "review": "string"
}

Response samples

Content type
application/json
{
  • "book_edition_id": "string",
  • "created_at": "string",
  • "date_finished": "string",
  • "date_started": "string",
  • "id": "string",
  • "is_favorite": true,
  • "notes": "string",
  • "rating": 0,
  • "read_status": "string",
  • "reread_count": 0,
  • "review": "string",
  • "updated_at": "string",
  • "user_id": "string"
}

Delete my reading interaction

Removes the current user's reading interaction for an edition.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

edition_id
required
string

Edition UUID

Responses

Browse default upload directory

Lists files and subdirectories within the server's configured ebook or audiobook upload path.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
format
required
string

ebook or audiobook

path
string

Relative sub-path (default: root)

Responses

series

Get series for a book

Returns all series that a specific book belongs to.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List series in a library

Returns all series defined in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
search
string

Filter by series name

tag
string

Filter by tag

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a series

Creates a new series in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Series details

demographic
string
description
string
external_id
string
external_source
string
genres
Array of strings
name
string
original_language
string
publication_year
integer
status
string
tag_ids
Array of strings
total_count
integer
url
string

Responses

Request samples

Content type
application/json
{
  • "demographic": "string",
  • "description": "string",
  • "external_id": "string",
  • "external_source": "string",
  • "genres": [
    ],
  • "name": "string",
  • "original_language": "string",
  • "publication_year": 0,
  • "status": "string",
  • "tag_ids": [
    ],
  • "total_count": 0,
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "created_at": "string",
  • "demographic": "string",
  • "description": "string",
  • "external_id": "string",
  • "external_source": "string",
  • "genres": [
    ],
  • "id": "string",
  • "is_complete": true,
  • "last_release_date": "string",
  • "library_id": "string",
  • "name": "string",
  • "next_release_date": "string",
  • "original_language": "string",
  • "publication_year": 0,
  • "status": "string",
  • "tags": [
    ],
  • "total_count": 0,
  • "updated_at": "string",
  • "url": "string"
}

Bulk-create series from suggestions

Creates each named series and adds the listed books at the given positions.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Series to create

series
Array of any

Responses

Request samples

Content type
application/json
{
  • "series": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "series": [
    ]
}

Suggest new series from ungrouped books

Scans books not yet in any series, detects volume-numbered titles, groups them by base name, and returns proposed new series. Does not modify state.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
media_type
string

Media type name filter (repeatable)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a series

Returns details for a specific series.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "created_at": "string",
  • "demographic": "string",
  • "description": "string",
  • "external_id": "string",
  • "external_source": "string",
  • "genres": [
    ],
  • "id": "string",
  • "is_complete": true,
  • "last_release_date": "string",
  • "library_id": "string",
  • "name": "string",
  • "next_release_date": "string",
  • "original_language": "string",
  • "publication_year": 0,
  • "status": "string",
  • "tags": [
    ],
  • "total_count": 0,
  • "updated_at": "string",
  • "url": "string"
}

Update a series

Replaces a series's metadata.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Request Body schema: application/json
required

Updated series

demographic
string
description
string
external_id
string
external_source
string
genres
Array of strings
name
string
original_language
string
publication_year
integer
status
string
tag_ids
Array of strings
total_count
integer
url
string

Responses

Request samples

Content type
application/json
{
  • "demographic": "string",
  • "description": "string",
  • "external_id": "string",
  • "external_source": "string",
  • "genres": [
    ],
  • "name": "string",
  • "original_language": "string",
  • "publication_year": 0,
  • "status": "string",
  • "tag_ids": [
    ],
  • "total_count": 0,
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "created_at": "string",
  • "demographic": "string",
  • "description": "string",
  • "external_id": "string",
  • "external_source": "string",
  • "genres": [
    ],
  • "id": "string",
  • "is_complete": true,
  • "last_release_date": "string",
  • "library_id": "string",
  • "name": "string",
  • "next_release_date": "string",
  • "original_language": "string",
  • "publication_year": 0,
  • "status": "string",
  • "tags": [
    ],
  • "total_count": 0,
  • "updated_at": "string",
  • "url": "string"
}

Delete a series

Permanently deletes a series (books are not deleted).

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

List books in a series

Returns all books in a series with their position.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add or update a book in a series

Sets the position of a book within a series (insert or update).

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Request Body schema: application/json
required

Book position

book_id
string
position
number

Responses

Request samples

Content type
application/json
{
  • "book_id": "string",
  • "position": 0
}

Remove a book from a series

Removes a book's membership from a series.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

book_id
required
string

Book UUID

Responses

Bulk-apply auto-match results

Upserts each (book_id, position) pair into the target series. Accepts the preview list that the caller has optionally tweaked.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Request Body schema: application/json
required

Matches to apply

matches
Array of any

Responses

Request samples

Content type
application/json
{
  • "matches": [
    ]
}

Response samples

Content type
application/json
{
  • "applied": 0
}

Auto-match library books to this series

Scans the library for books whose title begins with the series name plus a volume number, and returns a list of proposed (book, position) pairs along with any other series each book already belongs to. Does not modify state.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List series volumes

Returns known release volumes for a series from provider data.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sync series volumes from providers

Fetches the latest volume/release data from providers and stores it.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

series_id
required
string

Series UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

shelves

List shelves for a book

Returns all shelves that contain the given book.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

book_id
required
string

Book UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List shelves in a library

Returns all shelves for a library with book counts and tags.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
search
string

Filter by shelf name

tag
string

Filter by tag name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a shelf

Creates a new shelf in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Shelf details

color
string
description
string
display_order
integer
icon
string
name
string
tag_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "color": "string",
  • "description": "string",
  • "display_order": 0,
  • "icon": "string",
  • "name": "string",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "color": "string",
  • "created_at": "string",
  • "description": "string",
  • "display_order": 0,
  • "icon": "string",
  • "id": "string",
  • "library_id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "updated_at": "string"
}

Update a shelf

Replaces a shelf's metadata.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

shelf_id
required
string

Shelf UUID

Request Body schema: application/json
required

Updated shelf

color
string
description
string
display_order
integer
icon
string
name
string
tag_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "color": "string",
  • "description": "string",
  • "display_order": 0,
  • "icon": "string",
  • "name": "string",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "color": "string",
  • "created_at": "string",
  • "description": "string",
  • "display_order": 0,
  • "icon": "string",
  • "id": "string",
  • "library_id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "updated_at": "string"
}

Delete a shelf

Permanently deletes a shelf (books are not deleted).

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

shelf_id
required
string

Shelf UUID

Responses

List books on a shelf

Returns all books currently on the given shelf.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

shelf_id
required
string

Shelf UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a book to a shelf

Adds a book to the specified shelf.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

shelf_id
required
string

Shelf UUID

Request Body schema: application/json
required

Book to add

book_id
string

Responses

Request samples

Content type
application/json
{
  • "book_id": "string"
}

Remove a book from a shelf

Removes a book from the specified shelf.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

shelf_id
required
string

Shelf UUID

book_id
required
string

Book UUID

Responses

loans

List loans in a library

Returns current (and optionally returned) loans for a library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

query Parameters
include_returned
boolean

Include returned loans

search
string

Filter by borrower name

tag
string

Filter by tag

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a loan

Records that a book has been loaned to someone.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Loan details

book_id
string
due_date
string
loaned_at
string
loaned_to
string
notes
string
tag_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "book_id": "string",
  • "due_date": "string",
  • "loaned_at": "string",
  • "loaned_to": "string",
  • "notes": "string",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_id": "string",
  • "book_title": "string",
  • "created_at": "string",
  • "due_date": "string",
  • "id": "string",
  • "library_id": "string",
  • "loaned_at": "string",
  • "loaned_to": "string",
  • "notes": "string",
  • "returned_at": "string",
  • "tags": [
    ],
  • "updated_at": "string"
}

Delete a loan

Permanently deletes a loan record.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

loan_id
required
string

Loan UUID

Responses

Update a loan

Updates loan details including marking a book as returned.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

loan_id
required
string

Loan UUID

Request Body schema: application/json
required

Updated loan

due_date
string
loaned_to
string
notes
string
returned_at
string
tag_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "due_date": "string",
  • "loaned_to": "string",
  • "notes": "string",
  • "returned_at": "string",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "book_id": "string",
  • "book_title": "string",
  • "created_at": "string",
  • "due_date": "string",
  • "id": "string",
  • "library_id": "string",
  • "loaned_at": "string",
  • "loaned_to": "string",
  • "notes": "string",
  • "returned_at": "string",
  • "tags": [
    ],
  • "updated_at": "string"
}

storage-locations

Browse storage location directory

Lists files and subdirectories within a storage location at the given path.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

location_id
required
string

Storage location UUID

query Parameters
path
string

Relative sub-path (default: root)

Responses

tags

List tags in a library

Returns all tags defined in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a tag

Creates a new tag in the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

Request Body schema: application/json
required

Tag details

color
string
name
string

Responses

Request samples

Content type
application/json
{
  • "color": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "color": "string",
  • "created_at": "string",
  • "id": "string",
  • "library_id": "string",
  • "name": "string"
}

Update a tag

Updates the name and/or color of a tag.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

tag_id
required
string

Tag UUID

Request Body schema: application/json
required

Updated tag

color
string
name
string

Responses

Request samples

Content type
application/json
{
  • "color": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "color": "string",
  • "created_at": "string",
  • "id": "string",
  • "library_id": "string",
  • "name": "string"
}

Delete a tag

Permanently deletes a tag from the library.

Authorizations:
BearerAuth
path Parameters
library_id
required
string

Library UUID

tag_id
required
string

Tag UUID

Responses

lookup

Search books across providers

Queries all enabled providers for books matching the freetext query.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lookup book by ISBN

Queries all enabled providers and returns per-provider results.

Authorizations:
BearerAuth
path Parameters
isbn
required
string

ISBN-10 or ISBN-13

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lookup ISBN merged

Returns a single merged result across all providers with per-field source attribution.

Authorizations:
BearerAuth
path Parameters
isbn
required
string

ISBN-10 or ISBN-13

Responses

Response samples

Content type
application/json
{
  • "authors": {
    },
  • "categories": [
    ],
  • "covers": [
    ],
  • "description": {
    },
  • "isbn_10": {
    },
  • "isbn_13": {
    },
  • "language": {
    },
  • "page_count": {
    },
  • "publish_date": {
    },
  • "publisher": {
    },
  • "subtitle": {
    },
  • "title": {
    }
}

Search series across providers

Queries enabled providers for series matching the search term.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query

Responses

Response samples

Content type
application/json
[
  • {
    }
]

me

Get my AI preferences

Returns whether the caller has opted in to AI features.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "opt_in": true
}

Update my AI preferences

Sets whether the caller is opted in to AI features.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Opt-in flag

opt_in
boolean

Responses

Request samples

Content type
application/json
{
  • "opt_in": true
}

Response samples

Content type
application/json
{
  • "opt_in": true
}

List my AI suggestions

Returns the current AI-generated recommendations for the caller. Filter by type (buy | read_next) and status.

Authorizations:
BearerAuth
query Parameters
type
string

Filter by type: buy | read_next

status
string

Filter by status: new | dismissed | interested | added_to_library

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get my AI suggestion run quota

Returns how many suggestion runs the caller has used in the last 24h and the configured per-user daily limit.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "resets_at": "string",
  • "unlimited": true,
  • "used": 0
}

Trigger a suggestions run for the caller

Enqueues a background job to regenerate suggestions. Rate-limited by admin config.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

List my recent AI suggestion runs

Returns the caller's most recent suggestion runs with cost and status. Newest first.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get one of my AI suggestion runs

Returns the run metadata plus every pipeline event emitted during execution (prompt, AI responses, enrichment decisions, read_next matches, backfill passes).

Authorizations:
BearerAuth
path Parameters
id
required
string

Run ID

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "run": {
    }
}

Block a suggestion so it never reappears

Creates a persistent block scoped to the book, the author, or the series.

Authorizations:
BearerAuth
path Parameters
id
required
string

Suggestion ID

Request Body schema: application/json
required

Block scope: book | author | series

scope
string

Responses

Request samples

Content type
application/json
{
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Update a suggestion's status

Mark a suggestion as dismissed, interested, or added_to_library.

Authorizations:
BearerAuth
path Parameters
id
required
string

Suggestion ID

Request Body schema: application/json
required

New status

status
string

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Get my taste profile

Returns the JSON taste profile the user has saved. Empty object if none saved.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{ }

Update my taste profile

Replaces the saved taste profile with the supplied JSON object.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Taste profile JSON object

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

media-types

List media types

Returns all globally defined media types (book, manga, audiobook, etc.).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a media type (admin)

Creates a new global media type. Instance admin only.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Media type details

description
string
display_name
string
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "display_name": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "name": "string"
}

Update a media type (admin)

Updates the display name and description of a media type. Instance admin only.

Authorizations:
BearerAuth
path Parameters
media_type_id
required
string

Media type UUID

Request Body schema: application/json
required

Updated fields

description
string
display_name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "book_count": 0,
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "name": "string"
}

Delete a media type (admin)

Permanently deletes a media type. Fails if books are assigned to it. Instance admin only.

Authorizations:
BearerAuth
path Parameters
media_type_id
required
string

Media type UUID

Responses

setup

Create first instance admin

Creates the initial instance admin on a fresh install. Fails with 409 once any user exists.

Request Body schema: application/json
required

Admin account request

display_name
string
email
string
password
string
username
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "user": { }
}

Setup status

Returns whether the instance has been initialized (at least one user exists).

Responses

Response samples

Content type
application/json
{
  • "initialized": true
}