REST API ¶

User registered successfully

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "user_id": "string",
    "email": "name@example.com",
    "message": "string"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Email already registered

Example response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Too many requests

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": {
            "retry_after": 60
        }
    }
}

POST /auth/login¶

Login with email and password

Authenticates a user with email and password credentials. Returns access and refresh tokens on success.

Example request:

POST /auth/login HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "name@example.com",
    "password": "********"
}

Status Codes:

200 OK –

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "string",
    "expires_in": 1,
    "user": {
        "user_id": "string",
        "email": "name@example.com",
        "display_name": "string",
        "avatar_url": "https://example.com",
        "is_anonymous": true,
        "email_verified": true,
        "created_at": "2026-03-12T10:47:30.995488",
        "last_login_at": "2026-03-12T10:47:30.995488"
    }
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Invalid credentials

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Account not verified or disabled

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Too many requests

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": {
            "retry_after": 60
        }
    }
}

POST /auth/oauth/google¶

Login or register with Google OAuth

Authenticates a user via Google OAuth 2.0. Creates a new account if the Google email is not registered. Links Google account if email matches existing account.

Example request:

POST /auth/oauth/google HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id_token": "string"
}

Status Codes:

200 OK –

Authentication successful

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "string",
    "expires_in": 1,
    "user": {
        "user_id": "string",
        "email": "name@example.com",
        "display_name": "string",
        "avatar_url": "https://example.com",
        "is_anonymous": true,
        "email_verified": true,
        "created_at": "2026-03-12T10:47:30.995488",
        "last_login_at": "2026-03-12T10:47:30.995488"
    }
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Invalid OAuth token

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /auth/refresh¶

Refresh access token

Exchanges a valid refresh token for a new access token. The refresh token is rotated for security.

Example request:

POST /auth/refresh HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "refresh_token": "string"
}

Status Codes:

200 OK –

Token refreshed successfully

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "string",
    "expires_in": 1,
    "user": {
        "user_id": "string",
        "email": "name@example.com",
        "display_name": "string",
        "avatar_url": "https://example.com",
        "is_anonymous": true,
        "email_verified": true,
        "created_at": "2026-03-12T10:47:30.995488",
        "last_login_at": "2026-03-12T10:47:30.995488"
    }
}

Invalid or expired refresh token

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /auth/logout¶

Logout and invalidate tokens

Invalidates the current session and all associated tokens. Optionally invalidates all sessions for the user.

Example request:

POST /auth/logout HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "all_devices": true
}

Status Codes:

204 No Content – Logout successful

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /auth/verify-email¶

Verify email address

Verifies the user’s email address using the token sent via email. Activates the account on successful verification.

Example request:

POST /auth/verify-email HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "token": "string"
}

Status Codes:

200 OK –

Email verified successfully

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string"
}

Invalid or expired token

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /auth/resend-verification¶

Resend verification email

Sends a new verification email to the user’s registered address.

Example request:

POST /auth/resend-verification HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "name@example.com"
}

Status Codes:

200 OK –

Verification email sent (if account exists)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string"
}

Too many requests

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": {
            "retry_after": 60
        }
    }
}

POST /auth/forgot-password¶

Request password reset

Sends a password reset link to the user’s email. For security, always returns success even if email doesn’t exist.

Example request:

POST /auth/forgot-password HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "name@example.com"
}

Status Codes:

200 OK –

Password reset email sent (if account exists)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string"
}

Too many requests

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": {
            "retry_after": 60
        }
    }
}

POST /auth/reset-password¶

Reset password with token

Resets the user’s password using the token from the reset email. Invalidates all existing sessions after password change.

Example request:

POST /auth/reset-password HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "token": "string",
    "password": "********"
}

Status Codes:

200 OK –

Password reset successful

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string"
}

Invalid or expired token, or weak password

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Users¶

GET /users/me¶

Get current user profile

Returns the authenticated user’s profile information.

Example request:

GET /users/me HTTP/1.1
Host: example.com

Status Codes:

200 OK –

User profile

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": "string",
    "email": "name@example.com",
    "display_name": "string",
    "avatar_url": "https://example.com",
    "is_anonymous": true,
    "email_verified": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "last_login_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /users/me¶

Update current user profile

Updates the authenticated user’s profile information.

Example request:

PATCH /users/me HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "display_name": "string",
    "avatar_url": "https://example.com"
}

Status Codes:

200 OK –

Profile updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": "string",
    "email": "name@example.com",
    "display_name": "string",
    "avatar_url": "https://example.com",
    "is_anonymous": true,
    "email_verified": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "last_login_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /users/me¶

Delete current user account

Permanently deletes the user account and all associated data. Requires password confirmation for security. Data is scheduled for deletion within 30 days.

Example request:

DELETE /users/me HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "password": "********"
}

Status Codes:

204 No Content – Account scheduled for deletion

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Invalid password

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /users/me/preferences¶

Get user preferences

Returns the user’s application preferences.

Example request:

GET /users/me/preferences HTTP/1.1
Host: example.com

Status Codes:

200 OK –

User preferences

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "theme": "dark",
    "notifications_enabled": true,
    "default_shelf": "Currently Reading",
    "sync_wifi_only": false
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /users/me/preferences¶

Update user preferences

Updates the user’s application preferences.

Example request:

PUT /users/me/preferences HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "theme": "dark",
    "notifications_enabled": true,
    "default_shelf": "Currently Reading",
    "sync_wifi_only": false
}

Status Codes:

200 OK –

Preferences updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "theme": "dark",
    "notifications_enabled": true,
    "default_shelf": "Currently Reading",
    "sync_wifi_only": false
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /users/me/change-password¶

Change password

Changes the user’s password. Requires current password verification.

Example request:

POST /users/me/change-password HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "current_password": "********",
    "new_password": "********"
}

Status Codes:

200 OK –

Password changed successfully

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string"
}

Weak password

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Current password incorrect

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /reading-profiles¶

List reading profiles

Returns all reading profiles for the user.

Example request:

GET /reading-profiles HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of reading profiles

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "profiles": [
        {
            "profile_id": "string",
            "name": "string",
            "is_default": true,
            "font_family": "string",
            "font_size": 1,
            "font_weight": 1,
            "line_height": 1.0,
            "letter_spacing": 1.0,
            "paragraph_spacing": 1.0,
            "text_align": "left",
            "margin_horizontal": 1,
            "margin_vertical": 1,
            "background_color": "string",
            "text_color": "string",
            "link_color": "string",
            "selection_color": "string",
            "theme_mode": "light",
            "reading_mode": "paginated",
            "page_turn_animation": true,
            "column_count": 1,
            "hyphenation": true,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /reading-profiles¶

Create reading profile

Creates a new reading profile with viewer settings.

Example request:

POST /reading-profiles HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "is_default": true,
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true
}

Status Codes:

Profile created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "profile_id": "string",
    "name": "string",
    "is_default": true,
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /reading-profiles/{profile_id}¶

Get reading profile

Returns a specific reading profile.

Parameters:

profile_id (string)

Example request:

GET /reading-profiles/{profile_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Reading profile

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "profile_id": "string",
    "name": "string",
    "is_default": true,
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /reading-profiles/{profile_id}¶

Update reading profile

Updates reading profile settings.

Parameters:

profile_id (string)

Example request:

PATCH /reading-profiles/{profile_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true
}

Status Codes:

200 OK –

Profile updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "profile_id": "string",
    "name": "string",
    "is_default": true,
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /reading-profiles/{profile_id}¶

Delete reading profile

Deletes a reading profile. Cannot delete the default profile.

Parameters:

profile_id (string)

Status Codes:

204 No Content – Profile deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Cannot delete default profile

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /reading-profiles/{profile_id}/set-default¶

Set default reading profile

Sets this profile as the default for new books.

Parameters:

profile_id (string)

Status Codes:

200 OK –

Default profile set

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "profile_id": "string",
    "name": "string",
    "is_default": true,
    "font_family": "string",
    "font_size": 1,
    "font_weight": 1,
    "line_height": 1.0,
    "letter_spacing": 1.0,
    "paragraph_spacing": 1.0,
    "text_align": "left",
    "margin_horizontal": 1,
    "margin_vertical": 1,
    "background_color": "string",
    "text_color": "string",
    "link_color": "string",
    "selection_color": "string",
    "theme_mode": "light",
    "reading_mode": "paginated",
    "page_turn_animation": true,
    "column_count": 1,
    "hyphenation": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Books¶

GET /books¶

List user’s books

Returns a paginated list of books in the user’s library. Supports filtering, sorting, and search.

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page
sort (string) – Sort field with optional direction prefix. Prefix with - for descending order. Examples: title, -added_at, author
status (string) – Filter by reading status
shelf_id (string) – Filter by shelf
tag_id (string) – Filter by tag
series_id (string) – Filter by series
is_physical (boolean) – Filter by physical/digital
is_favorite (boolean) – Filter favorites only
search (string) – Search in title, author, description
query (string) – Advanced query language filter

Example request:

GET /books HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of books

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "books": [
        {
            "book_id": "string",
            "title": "string",
            "subtitle": "string",
            "author": "string",
            "co_authors": [
                "string"
            ],
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "language": "string",
            "page_count": 1,
            "description": "string",
            "cover_image_url": "https://example.com",
            "series_id": "string",
            "series_name": "string",
            "series_number": 1.0,
            "file_path": "string",
            "file_format": "epub",
            "file_size": 1,
            "file_hash": "string",
            "storage_backend_id": "string",
            "is_physical": true,
            "physical_location": "string",
            "lent_to": "string",
            "lent_at": "2026-03-12T10:47:30.995488",
            "is_favorite": true,
            "rating": 1,
            "reading_status": "not_started",
            "current_page": 1,
            "current_position": 1.0,
            "current_cfi": "string",
            "started_at": "2026-03-12T10:47:30.995488",
            "completed_at": "2026-03-12T10:47:30.995488",
            "added_at": "2026-03-12T10:47:30.995488",
            "last_read_at": "2026-03-12T10:47:30.995488",
            "custom_metadata": {},
            "is_ocr_processed": true,
            "ocr_confidence": 1.0,
            "updated_at": "2026-03-12T10:47:30.995488",
            "shelves": [
                {
                    "shelf_id": "string",
                    "name": "string",
                    "color": "string"
                }
            ],
            "tags": [
                {
                    "tag_id": "string",
                    "name": "string",
                    "color": "string",
                    "description": "string",
                    "usage_count": 1,
                    "created_at": "2026-03-12T10:47:30.995488"
                }
            ]
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books¶

Create a new book

Adds a new book to the user’s library. For digital books, use the file upload endpoint first.

Example request:

POST /books HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_number": 1.0,
    "file_path": "string",
    "file_format": "string",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "is_physical": true,
    "physical_location": "string",
    "custom_metadata": {},
    "shelf_ids": [
        "string"
    ],
    "tag_ids": [
        "string"
    ]
}

Status Codes:

Book created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "book_id": "string",
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_name": "string",
    "series_number": 1.0,
    "file_path": "string",
    "file_format": "epub",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "is_physical": true,
    "physical_location": "string",
    "lent_to": "string",
    "lent_at": "2026-03-12T10:47:30.995488",
    "is_favorite": true,
    "rating": 1,
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "added_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "custom_metadata": {},
    "is_ocr_processed": true,
    "ocr_confidence": 1.0,
    "updated_at": "2026-03-12T10:47:30.995488",
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "color": "string"
        }
    ],
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}¶

Get book details

Returns detailed information about a specific book.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Book details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "book_id": "string",
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_name": "string",
    "series_number": 1.0,
    "file_path": "string",
    "file_format": "epub",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "is_physical": true,
    "physical_location": "string",
    "lent_to": "string",
    "lent_at": "2026-03-12T10:47:30.995488",
    "is_favorite": true,
    "rating": 1,
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "added_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "custom_metadata": {},
    "is_ocr_processed": true,
    "ocr_confidence": 1.0,
    "updated_at": "2026-03-12T10:47:30.995488",
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "color": "string"
        }
    ],
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /books/{book_id}¶

Update book metadata

Updates book metadata fields.

Parameters:

book_id (string) – Book ID

Example request:

PATCH /books/{book_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_number": 1.0,
    "is_physical": true,
    "physical_location": "string",
    "lent_to": "string",
    "lent_at": "2026-03-12T10:47:30.995488",
    "is_favorite": true,
    "rating": 1,
    "reading_status": "not_started",
    "custom_metadata": {}
}

Status Codes:

200 OK –

Book updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "book_id": "string",
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_name": "string",
    "series_number": 1.0,
    "file_path": "string",
    "file_format": "epub",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "is_physical": true,
    "physical_location": "string",
    "lent_to": "string",
    "lent_at": "2026-03-12T10:47:30.995488",
    "is_favorite": true,
    "rating": 1,
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "added_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "custom_metadata": {},
    "is_ocr_processed": true,
    "ocr_confidence": 1.0,
    "updated_at": "2026-03-12T10:47:30.995488",
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "color": "string"
        }
    ],
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /books/{book_id}¶

Delete a book

Removes a book from the library. Optionally deletes the associated file from storage.

Parameters:

book_id (string) – Book ID

Query Parameters:

delete_file (boolean) – Also delete the book file from storage

Status Codes:

204 No Content – Book deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/cover¶

Get book cover image

Returns the book’s cover image.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/cover HTTP/1.1
Host: example.com

Status Codes:

200 OK – Cover image
302 Found – Redirect to cover URL

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /books/{book_id}/cover¶

Upload book cover image

Uploads or replaces the book’s cover image.

Parameters:

book_id (string) – Book ID

Example request:

PUT /books/{book_id}/cover HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "url": "https://example.com"
}

Status Codes:

200 OK –

Cover uploaded

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "book_id": "string",
    "title": "string",
    "subtitle": "string",
    "author": "string",
    "co_authors": [
        "string"
    ],
    "isbn": "string",
    "isbn13": "string",
    "publication_date": "2026-03-12",
    "publisher": "string",
    "language": "string",
    "page_count": 1,
    "description": "string",
    "cover_image_url": "https://example.com",
    "series_id": "string",
    "series_name": "string",
    "series_number": 1.0,
    "file_path": "string",
    "file_format": "epub",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "is_physical": true,
    "physical_location": "string",
    "lent_to": "string",
    "lent_at": "2026-03-12T10:47:30.995488",
    "is_favorite": true,
    "rating": 1,
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "added_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "custom_metadata": {},
    "is_ocr_processed": true,
    "ocr_confidence": 1.0,
    "updated_at": "2026-03-12T10:47:30.995488",
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "color": "string"
        }
    ],
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/shelves¶

Get book’s shelves

Returns the shelves this book belongs to.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/shelves HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of shelves

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "description": "string",
            "color": "string",
            "icon": "string",
            "is_default": true,
            "is_smart": true,
            "smart_query": "string",
            "sort_order": 1,
            "parent_shelf_id": "string",
            "book_count": 1,
            "children": [
                {}
            ],
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /books/{book_id}/shelves¶

Set book’s shelves

Replaces all shelf assignments for this book.

Parameters:

book_id (string) – Book ID

Example request:

PUT /books/{book_id}/shelves HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "shelf_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Shelves updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "description": "string",
            "color": "string",
            "icon": "string",
            "is_default": true,
            "is_smart": true,
            "smart_query": "string",
            "sort_order": 1,
            "parent_shelf_id": "string",
            "book_count": 1,
            "children": [
                {}
            ],
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/tags¶

Get book’s tags

Returns the tags assigned to this book.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/tags HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of tags

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /books/{book_id}/tags¶

Set book’s tags

Replaces all tag assignments for this book. Maximum 10 tags per book.

Parameters:

book_id (string) – Book ID

Example request:

PUT /books/{book_id}/tags HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "tag_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Tags updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/progress¶

Get reading progress

Returns the current reading progress for a book.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/progress HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Reading progress

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "book_id": "string",
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "total_reading_time_minutes": 1,
    "sessions_count": 1
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /books/{book_id}/progress¶

Update reading progress

Updates the reading position and status for a book.

Parameters:

book_id (string) – Book ID

Example request:

PUT /books/{book_id}/progress HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string"
}

Status Codes:

200 OK –

Progress updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "book_id": "string",
    "reading_status": "not_started",
    "current_page": 1,
    "current_position": 1.0,
    "current_cfi": "string",
    "started_at": "2026-03-12T10:47:30.995488",
    "completed_at": "2026-03-12T10:47:30.995488",
    "last_read_at": "2026-03-12T10:47:30.995488",
    "total_reading_time_minutes": 1,
    "sessions_count": 1
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books/batch¶

Batch create books

Creates multiple books in a single request. Useful for bulk imports. Maximum 50 books per request.

Example request:

POST /books/batch HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "books": [
        {
            "title": "string",
            "subtitle": "string",
            "author": "string",
            "co_authors": [
                "string"
            ],
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "language": "string",
            "page_count": 1,
            "description": "string",
            "cover_image_url": "https://example.com",
            "series_id": "string",
            "series_number": 1.0,
            "file_path": "string",
            "file_format": "string",
            "file_size": 1,
            "file_hash": "string",
            "storage_backend_id": "string",
            "is_physical": true,
            "physical_location": "string",
            "custom_metadata": {},
            "shelf_ids": [
                "string"
            ],
            "tag_ids": [
                "string"
            ]
        }
    ]
}

Status Codes:

Books created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "created": [
        {
            "book_id": "string",
            "title": "string",
            "subtitle": "string",
            "author": "string",
            "co_authors": [
                "string"
            ],
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "language": "string",
            "page_count": 1,
            "description": "string",
            "cover_image_url": "https://example.com",
            "series_id": "string",
            "series_name": "string",
            "series_number": 1.0,
            "file_path": "string",
            "file_format": "epub",
            "file_size": 1,
            "file_hash": "string",
            "storage_backend_id": "string",
            "is_physical": true,
            "physical_location": "string",
            "lent_to": "string",
            "lent_at": "2026-03-12T10:47:30.995488",
            "is_favorite": true,
            "rating": 1,
            "reading_status": "not_started",
            "current_page": 1,
            "current_position": 1.0,
            "current_cfi": "string",
            "started_at": "2026-03-12T10:47:30.995488",
            "completed_at": "2026-03-12T10:47:30.995488",
            "added_at": "2026-03-12T10:47:30.995488",
            "last_read_at": "2026-03-12T10:47:30.995488",
            "custom_metadata": {},
            "is_ocr_processed": true,
            "ocr_confidence": 1.0,
            "updated_at": "2026-03-12T10:47:30.995488",
            "shelves": [
                {
                    "shelf_id": "string",
                    "name": "string",
                    "color": "string"
                }
            ],
            "tags": [
                {
                    "tag_id": "string",
                    "name": "string",
                    "color": "string",
                    "description": "string",
                    "usage_count": 1,
                    "created_at": "2026-03-12T10:47:30.995488"
                }
            ]
        }
    ],
    "errors": [
        {
            "index": 1,
            "error": {
                "error": {
                    "code": "string",
                    "message": "string",
                    "details": {}
                }
            }
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /books/batch¶

Batch update books

Updates multiple books in a single request. Useful for bulk tagging, shelf assignment, or status changes.

Example request:

PATCH /books/batch HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_ids": [
        "string"
    ],
    "updates": {
        "reading_status": "not_started",
        "is_favorite": true,
        "rating": 1
    },
    "add_tag_ids": [
        "string"
    ],
    "remove_tag_ids": [
        "string"
    ],
    "add_shelf_ids": [
        "string"
    ],
    "remove_shelf_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Books updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "updated_count": 1,
    "errors": [
        {
            "book_id": "string",
            "error": {
                "error": {
                    "code": "string",
                    "message": "string",
                    "details": {}
                }
            }
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /books/batch¶

Batch delete books

Deletes multiple books in a single request. Optionally deletes associated files from storage.

Example request:

DELETE /books/batch HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_ids": [
        "string"
    ],
    "delete_files": true
}

Status Codes:

200 OK –

Books deleted

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "deleted_count": 1,
    "errors": [
        {
            "book_id": "string",
            "error": {
                "error": {
                    "code": "string",
                    "message": "string",
                    "details": {}
                }
            }
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books/metadata/fetch¶

Fetch metadata from online sources

Searches online sources (Open Library, Google Books) for book metadata. Returns multiple matches for user selection.

Example request:

POST /books/metadata/fetch HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "isbn": "string",
    "title": "string",
    "author": "string"
}

Status Codes:

200 OK –

Metadata search results

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "source": "open_library",
            "title": "string",
            "author": "string",
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "description": "string",
            "cover_image_url": "https://example.com",
            "page_count": 1,
            "language": "string"
        }
    ]
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /saved-filters¶

List saved filters

Returns all saved search/filter queries.

Example request:

GET /saved-filters HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of saved filters

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "filters": [
        {
            "filter_id": "string",
            "name": "string",
            "description": "string",
            "query": "string",
            "filter_type": "search",
            "icon": "string",
            "color": "string",
            "is_pinned": true,
            "usage_count": 1,
            "last_used_at": "2026-03-12T10:47:30.995488",
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /saved-filters¶

Create saved filter

Saves a search/filter query for reuse.

Example request:

POST /saved-filters HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "query": "string",
    "filter_type": "search",
    "icon": "string",
    "color": "string",
    "is_pinned": true
}

Status Codes:

Filter saved

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "filter_id": "string",
    "name": "string",
    "description": "string",
    "query": "string",
    "filter_type": "search",
    "icon": "string",
    "color": "string",
    "is_pinned": true,
    "usage_count": 1,
    "last_used_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /saved-filters/{filter_id}¶

Get saved filter

Returns a specific saved filter.

Parameters:

filter_id (string)

Example request:

GET /saved-filters/{filter_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Saved filter

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "filter_id": "string",
    "name": "string",
    "description": "string",
    "query": "string",
    "filter_type": "search",
    "icon": "string",
    "color": "string",
    "is_pinned": true,
    "usage_count": 1,
    "last_used_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /saved-filters/{filter_id}¶

Update saved filter

Updates a saved filter.

Parameters:

filter_id (string)

Example request:

PATCH /saved-filters/{filter_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "query": "string",
    "filter_type": "search",
    "icon": "string",
    "color": "string",
    "is_pinned": true
}

Status Codes:

200 OK –

Filter updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "filter_id": "string",
    "name": "string",
    "description": "string",
    "query": "string",
    "filter_type": "search",
    "icon": "string",
    "color": "string",
    "is_pinned": true,
    "usage_count": 1,
    "last_used_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /saved-filters/{filter_id}¶

Delete saved filter

Deletes a saved filter.

Parameters:

filter_id (string)

Status Codes:

204 No Content – Filter deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /export/library¶

Export library data

Exports library data in structured format.

Example request:

POST /export/library HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "format": "json",
    "include_books": true,
    "include_annotations": true,
    "include_notes": true,
    "include_progress": true,
    "shelf_ids": [
        "string"
    ],
    "tag_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Export file

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

01010101

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Shelves¶

GET /shelves¶

List all shelves

Returns all shelves for the user, including nested structure.

Query Parameters:

include_books (boolean) – Include book counts
flat (boolean) – Return flat list instead of tree

Example request:

GET /shelves HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of shelves

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shelves": [
        {
            "shelf_id": "string",
            "name": "string",
            "description": "string",
            "color": "string",
            "icon": "string",
            "is_default": true,
            "is_smart": true,
            "smart_query": "string",
            "sort_order": 1,
            "parent_shelf_id": "string",
            "book_count": 1,
            "children": [
                {}
            ],
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /shelves¶

Create a new shelf

Creates a new shelf or sub-shelf.

Example request:

POST /shelves HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "color": "string",
    "icon": "string",
    "parent_shelf_id": "string",
    "is_smart": true,
    "smart_query": "string",
    "sort_order": 1
}

Status Codes:

Shelf created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "shelf_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "icon": "string",
    "is_default": true,
    "is_smart": true,
    "smart_query": "string",
    "sort_order": 1,
    "parent_shelf_id": "string",
    "book_count": 1,
    "children": [
        {}
    ],
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Shelf name already exists at this level

Example response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /shelves/{shelf_id}¶

Get shelf details

Returns detailed information about a shelf.

Parameters:

shelf_id (string) – Shelf ID

Example request:

GET /shelves/{shelf_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Shelf details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shelf_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "icon": "string",
    "is_default": true,
    "is_smart": true,
    "smart_query": "string",
    "sort_order": 1,
    "parent_shelf_id": "string",
    "book_count": 1,
    "children": [
        {}
    ],
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /shelves/{shelf_id}¶

Update shelf

Updates shelf properties.

Parameters:

shelf_id (string) – Shelf ID

Example request:

PATCH /shelves/{shelf_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "color": "string",
    "icon": "string",
    "parent_shelf_id": "string",
    "is_smart": true,
    "smart_query": "string",
    "sort_order": 1
}

Status Codes:

200 OK –

Shelf updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shelf_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "icon": "string",
    "is_default": true,
    "is_smart": true,
    "smart_query": "string",
    "sort_order": 1,
    "parent_shelf_id": "string",
    "book_count": 1,
    "children": [
        {}
    ],
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /shelves/{shelf_id}¶

Delete shelf

Deletes a shelf. Books in the shelf are not deleted. Cannot delete default shelves.

Parameters:

shelf_id (string) – Shelf ID

Status Codes:

204 No Content – Shelf deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Cannot delete default shelf

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /shelves/{shelf_id}/books¶

List books in shelf

Returns books in this shelf with pagination.

Parameters:

shelf_id (string) – Shelf ID

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page
sort (string) – Sort field with optional direction prefix. Prefix with - for descending order. Examples: title, -added_at, author

Example request:

GET /shelves/{shelf_id}/books HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of books

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "books": [
        {
            "book_id": "string",
            "title": "string",
            "subtitle": "string",
            "author": "string",
            "co_authors": [
                "string"
            ],
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "language": "string",
            "page_count": 1,
            "description": "string",
            "cover_image_url": "https://example.com",
            "series_id": "string",
            "series_name": "string",
            "series_number": 1.0,
            "file_path": "string",
            "file_format": "epub",
            "file_size": 1,
            "file_hash": "string",
            "storage_backend_id": "string",
            "is_physical": true,
            "physical_location": "string",
            "lent_to": "string",
            "lent_at": "2026-03-12T10:47:30.995488",
            "is_favorite": true,
            "rating": 1,
            "reading_status": "not_started",
            "current_page": 1,
            "current_position": 1.0,
            "current_cfi": "string",
            "started_at": "2026-03-12T10:47:30.995488",
            "completed_at": "2026-03-12T10:47:30.995488",
            "added_at": "2026-03-12T10:47:30.995488",
            "last_read_at": "2026-03-12T10:47:30.995488",
            "custom_metadata": {},
            "is_ocr_processed": true,
            "ocr_confidence": 1.0,
            "updated_at": "2026-03-12T10:47:30.995488",
            "shelves": [
                {
                    "shelf_id": "string",
                    "name": "string",
                    "color": "string"
                }
            ],
            "tags": [
                {
                    "tag_id": "string",
                    "name": "string",
                    "color": "string",
                    "description": "string",
                    "usage_count": 1,
                    "created_at": "2026-03-12T10:47:30.995488"
                }
            ]
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /shelves/{shelf_id}/books¶

Add books to shelf

Adds one or more books to the shelf.

Parameters:

shelf_id (string) – Shelf ID

Example request:

POST /shelves/{shelf_id}/books HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Books added

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "added_count": 1
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /shelves/{shelf_id}/books/remove¶

Remove books from shelf

Removes one or more books from the shelf.

Parameters:

shelf_id (string) – Shelf ID

Example request:

POST /shelves/{shelf_id}/books/remove HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_ids": [
        "string"
    ]
}

Status Codes:

200 OK –

Books removed

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "removed_count": 1
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Tags¶

GET /tags¶

List all tags

Returns all tags for the user.

Query Parameters:

include_counts (boolean) – Include book counts for each tag

Example request:

GET /tags HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of tags

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tags": [
        {
            "tag_id": "string",
            "name": "string",
            "color": "string",
            "description": "string",
            "usage_count": 1,
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /tags¶

Create a new tag

Creates a new tag with name and color.

Example request:

POST /tags HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "color": "string",
    "description": "string"
}

Status Codes:

Tag created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "tag_id": "string",
    "name": "string",
    "color": "string",
    "description": "string",
    "usage_count": 1,
    "created_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Tag name already exists

Example response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /tags/{tag_id}¶

Get tag details

Returns detailed information about a tag.

Parameters:

tag_id (string) – Tag ID

Example request:

GET /tags/{tag_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Tag details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tag_id": "string",
    "name": "string",
    "color": "string",
    "description": "string",
    "usage_count": 1,
    "created_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /tags/{tag_id}¶

Update tag

Updates tag name or color.

Parameters:

tag_id (string) – Tag ID

Example request:

PATCH /tags/{tag_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "color": "string",
    "description": "string"
}

Status Codes:

200 OK –

Tag updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tag_id": "string",
    "name": "string",
    "color": "string",
    "description": "string",
    "usage_count": 1,
    "created_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /tags/{tag_id}¶

Delete tag

Deletes a tag and removes it from all books.

Parameters:

tag_id (string) – Tag ID

Status Codes:

204 No Content – Tag deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /tags/{tag_id}/books¶

List books with tag

Returns books that have this tag.

Parameters:

tag_id (string) – Tag ID

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page

Example request:

GET /tags/{tag_id}/books HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of books

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "books": [
        {
            "book_id": "string",
            "title": "string",
            "subtitle": "string",
            "author": "string",
            "co_authors": [
                "string"
            ],
            "isbn": "string",
            "isbn13": "string",
            "publication_date": "2026-03-12",
            "publisher": "string",
            "language": "string",
            "page_count": 1,
            "description": "string",
            "cover_image_url": "https://example.com",
            "series_id": "string",
            "series_name": "string",
            "series_number": 1.0,
            "file_path": "string",
            "file_format": "epub",
            "file_size": 1,
            "file_hash": "string",
            "storage_backend_id": "string",
            "is_physical": true,
            "physical_location": "string",
            "lent_to": "string",
            "lent_at": "2026-03-12T10:47:30.995488",
            "is_favorite": true,
            "rating": 1,
            "reading_status": "not_started",
            "current_page": 1,
            "current_position": 1.0,
            "current_cfi": "string",
            "started_at": "2026-03-12T10:47:30.995488",
            "completed_at": "2026-03-12T10:47:30.995488",
            "added_at": "2026-03-12T10:47:30.995488",
            "last_read_at": "2026-03-12T10:47:30.995488",
            "custom_metadata": {},
            "is_ocr_processed": true,
            "ocr_confidence": 1.0,
            "updated_at": "2026-03-12T10:47:30.995488",
            "shelves": [
                {
                    "shelf_id": "string",
                    "name": "string",
                    "color": "string"
                }
            ],
            "tags": [
                {
                    "tag_id": "string",
                    "name": "string",
                    "color": "string",
                    "description": "string",
                    "usage_count": 1,
                    "created_at": "2026-03-12T10:47:30.995488"
                }
            ]
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Series¶

GET /series¶

List all series

Returns all series for the user.

Query Parameters:

include_books (boolean) – Include book counts

Example request:

GET /series HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of series

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "series": [
        {
            "series_id": "string",
            "name": "string",
            "description": "string",
            "author": "string",
            "total_books": 1,
            "is_complete": true,
            "book_count": 1,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /series¶

Create a new series

Creates a new series.

Example request:

POST /series HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "author": "string",
    "total_books": 1,
    "is_complete": true
}

Status Codes:

Series created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "series_id": "string",
    "name": "string",
    "description": "string",
    "author": "string",
    "total_books": 1,
    "is_complete": true,
    "book_count": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Series name already exists

Example response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /series/{series_id}¶

Get series details

Returns detailed information about a series including its books.

Parameters:

series_id (string) – Series ID

Example request:

GET /series/{series_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Series details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "series_id": "string",
    "name": "string",
    "description": "string",
    "author": "string",
    "total_books": 1,
    "is_complete": true,
    "book_count": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488",
    "books": [
        {
            "book_id": "string",
            "title": "string",
            "author": "string",
            "cover_image_url": "https://example.com",
            "reading_status": "not_started",
            "current_position": 1.0,
            "is_favorite": true,
            "rating": 1
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /series/{series_id}¶

Update series

Updates series information.

Parameters:

series_id (string) – Series ID

Example request:

PATCH /series/{series_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "author": "string",
    "total_books": 1,
    "is_complete": true
}

Status Codes:

200 OK –

Series updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "series_id": "string",
    "name": "string",
    "description": "string",
    "author": "string",
    "total_books": 1,
    "is_complete": true,
    "book_count": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /series/{series_id}¶

Delete series

Deletes a series. Books in the series are not deleted.

Parameters:

series_id (string) – Series ID

Status Codes:

204 No Content – Series deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Annotations¶

GET /annotations¶

List all annotations

Returns all annotations across all books.

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page
book_id (string) – Filter by book
color (string) – Filter by highlight color
search (string) – Search in highlighted text and notes

Example request:

GET /annotations HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of annotations

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "annotations": [
        {
            "annotation_id": "string",
            "book_id": "string",
            "book_title": "string",
            "selected_text": "string",
            "note": "string",
            "highlight_color": "string",
            "start_position": "string",
            "end_position": "string",
            "chapter_title": "string",
            "chapter_index": 1,
            "page_number": 1,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /annotations/export¶

Export annotations

Exports annotations to a structured file format. Can export all annotations or filter by book/color.

Example request:

POST /annotations/export HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "format": "markdown",
    "book_ids": [
        "string"
    ],
    "colors": [
        "string"
    ],
    "include_notes": true,
    "include_context": true,
    "group_by": "book"
}

Status Codes:

200 OK –

Export file

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

01010101

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/annotations¶

List book annotations

Returns all annotations for a specific book.

Parameters:

book_id (string) – Book ID

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page

Example request:

GET /books/{book_id}/annotations HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of annotations

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "annotations": [
        {
            "annotation_id": "string",
            "book_id": "string",
            "book_title": "string",
            "selected_text": "string",
            "note": "string",
            "highlight_color": "string",
            "start_position": "string",
            "end_position": "string",
            "chapter_title": "string",
            "chapter_index": 1,
            "page_number": 1,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books/{book_id}/annotations¶

Create annotation

Creates a new text highlight annotation.

Parameters:

book_id (string) – Book ID

Example request:

POST /books/{book_id}/annotations HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "selected_text": "string",
    "note": "string",
    "highlight_color": "string",
    "start_position": "string",
    "end_position": "string",
    "chapter_title": "string",
    "chapter_index": 1,
    "page_number": 1
}

Status Codes:

Annotation created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "annotation_id": "string",
    "book_id": "string",
    "book_title": "string",
    "selected_text": "string",
    "note": "string",
    "highlight_color": "string",
    "start_position": "string",
    "end_position": "string",
    "chapter_title": "string",
    "chapter_index": 1,
    "page_number": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/annotations/export¶

Export book annotations

Exports all annotations for a specific book.

Parameters:

book_id (string) – Book ID

Query Parameters:

format (string) – (Required)
include_notes (boolean)
include_context (boolean)

Example request:

GET /books/{book_id}/annotations/export?format=markdown HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Export file

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

01010101

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /annotations/{annotation_id}¶

Get annotation details

Returns detailed information about an annotation.

Parameters:

annotation_id (string) – Annotation ID

Example request:

GET /annotations/{annotation_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Annotation details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "annotation_id": "string",
    "book_id": "string",
    "book_title": "string",
    "selected_text": "string",
    "note": "string",
    "highlight_color": "string",
    "start_position": "string",
    "end_position": "string",
    "chapter_title": "string",
    "chapter_index": 1,
    "page_number": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /annotations/{annotation_id}¶

Update annotation

Updates annotation color or note.

Parameters:

annotation_id (string) – Annotation ID

Example request:

PATCH /annotations/{annotation_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "note": "string",
    "highlight_color": "string"
}

Status Codes:

200 OK –

Annotation updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "annotation_id": "string",
    "book_id": "string",
    "book_title": "string",
    "selected_text": "string",
    "note": "string",
    "highlight_color": "string",
    "start_position": "string",
    "end_position": "string",
    "chapter_title": "string",
    "chapter_index": 1,
    "page_number": 1,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /annotations/{annotation_id}¶

Delete annotation

Deletes an annotation.

Parameters:

annotation_id (string) – Annotation ID

Status Codes:

204 No Content – Annotation deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Notes¶

GET /notes¶

List all notes

Returns all notes across all books.

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page
book_id (string) – Filter by book
search (string) – Search in note title and content

Example request:

GET /notes HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of notes

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "notes": [
        {
            "note_id": "string",
            "book_id": "string",
            "book_title": "string",
            "title": "string",
            "content": "string",
            "is_pinned": true,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/notes¶

List book notes

Returns all notes for a specific book.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/notes HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of notes

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "notes": [
        {
            "note_id": "string",
            "book_id": "string",
            "book_title": "string",
            "title": "string",
            "content": "string",
            "is_pinned": true,
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books/{book_id}/notes¶

Create note

Creates a new free-form note for a book.

Parameters:

book_id (string) – Book ID

Example request:

POST /books/{book_id}/notes HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "content": "string",
    "is_pinned": true
}

Status Codes:

Note created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "note_id": "string",
    "book_id": "string",
    "book_title": "string",
    "title": "string",
    "content": "string",
    "is_pinned": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /notes/{note_id}¶

Get note details

Returns detailed information about a note.

Parameters:

note_id (string) – Note ID

Example request:

GET /notes/{note_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Note details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "note_id": "string",
    "book_id": "string",
    "book_title": "string",
    "title": "string",
    "content": "string",
    "is_pinned": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /notes/{note_id}¶

Update note

Updates note title or content.

Parameters:

note_id (string) – Note ID

Example request:

PATCH /notes/{note_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "content": "string",
    "is_pinned": true
}

Status Codes:

200 OK –

Note updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "note_id": "string",
    "book_id": "string",
    "book_title": "string",
    "title": "string",
    "content": "string",
    "is_pinned": true,
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /notes/{note_id}¶

Delete note

Deletes a note.

Parameters:

note_id (string) – Note ID

Status Codes:

204 No Content – Note deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Bookmarks¶

GET /books/{book_id}/bookmarks¶

List book bookmarks

Returns all bookmarks for a specific book.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/bookmarks HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of bookmarks

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "bookmarks": [
        {
            "bookmark_id": "string",
            "book_id": "string",
            "position": "string",
            "page_number": 1,
            "chapter_title": "string",
            "note": "string",
            "color": "string",
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /books/{book_id}/bookmarks¶

Create bookmark

Creates a new bookmark at a specific position.

Parameters:

book_id (string) – Book ID

Example request:

POST /books/{book_id}/bookmarks HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "position": "string",
    "page_number": 1,
    "chapter_title": "string",
    "note": "string",
    "color": "string"
}

Status Codes:

Bookmark created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "bookmark_id": "string",
    "book_id": "string",
    "position": "string",
    "page_number": 1,
    "chapter_title": "string",
    "note": "string",
    "color": "string",
    "created_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /bookmarks/{bookmark_id}¶

Get bookmark details

Returns detailed information about a bookmark.

Parameters:

bookmark_id (string) – Bookmark ID

Example request:

GET /bookmarks/{bookmark_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Bookmark details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "bookmark_id": "string",
    "book_id": "string",
    "position": "string",
    "page_number": 1,
    "chapter_title": "string",
    "note": "string",
    "color": "string",
    "created_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /bookmarks/{bookmark_id}¶

Update bookmark

Updates bookmark note or color.

Parameters:

bookmark_id (string) – Bookmark ID

Example request:

PATCH /bookmarks/{bookmark_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "note": "string",
    "color": "string"
}

Status Codes:

200 OK –

Bookmark updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "bookmark_id": "string",
    "book_id": "string",
    "position": "string",
    "page_number": 1,
    "chapter_title": "string",
    "note": "string",
    "color": "string",
    "created_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /bookmarks/{bookmark_id}¶

Delete bookmark

Deletes a bookmark.

Parameters:

bookmark_id (string) – Bookmark ID

Status Codes:

204 No Content – Bookmark deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Progress¶

GET /progress/sessions¶

List reading sessions

Returns reading session history.

Query Parameters:

page (integer) – Page number
limit (integer) – Items per page
book_id (string) – Filter by book
start_date (string) – Filter sessions after this date
end_date (string) – Filter sessions before this date

Example request:

GET /progress/sessions HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of reading sessions

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sessions": [
        {
            "session_id": "string",
            "book_id": "string",
            "book_title": "string",
            "start_time": "2026-03-12T10:47:30.995488",
            "end_time": "2026-03-12T10:47:30.995488",
            "start_position": 1.0,
            "end_position": 1.0,
            "pages_read": 1,
            "duration_minutes": 1,
            "device_type": "string",
            "device_name": "string",
            "created_at": "2026-03-12T10:47:30.995488"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 1,
        "total": 1,
        "total_pages": 1,
        "has_next": true,
        "has_prev": true
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /progress/sessions¶

Record reading session

Records a completed reading session.

Example request:

POST /progress/sessions HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_id": "string",
    "start_time": "2026-03-12T10:47:30.995488",
    "end_time": "2026-03-12T10:47:30.995488",
    "start_position": 1.0,
    "end_position": 1.0,
    "pages_read": 1,
    "device_type": "string",
    "device_name": "string"
}

Status Codes:

Session recorded

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "session_id": "string",
    "book_id": "string",
    "book_title": "string",
    "start_time": "2026-03-12T10:47:30.995488",
    "end_time": "2026-03-12T10:47:30.995488",
    "start_position": 1.0,
    "end_position": 1.0,
    "pages_read": 1,
    "duration_minutes": 1,
    "device_type": "string",
    "device_name": "string",
    "created_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /progress/sessions/{session_id}¶

Get session details

Returns detailed information about a reading session.

Parameters:

session_id (string)

Example request:

GET /progress/sessions/{session_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Session details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "session_id": "string",
    "book_id": "string",
    "book_title": "string",
    "start_time": "2026-03-12T10:47:30.995488",
    "end_time": "2026-03-12T10:47:30.995488",
    "start_position": 1.0,
    "end_position": 1.0,
    "pages_read": 1,
    "duration_minutes": 1,
    "device_type": "string",
    "device_name": "string",
    "created_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /progress/sessions/{session_id}¶

Delete session

Deletes a reading session record.

Parameters:

session_id (string)

Status Codes:

204 No Content – Session deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /progress/statistics¶

Get reading statistics

Returns aggregated reading statistics.

Query Parameters:

period (string)
start_date (string) – Start date for custom period
end_date (string) – End date for custom period
book_id (string) – Statistics for specific book
shelf_id (string) – Statistics for books in shelf

Example request:

GET /progress/statistics HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Reading statistics

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "period": {
        "start_date": "2026-03-12",
        "end_date": "2026-03-12"
    },
    "totals": {
        "reading_time_minutes": 1,
        "pages_read": 1,
        "books_completed": 1,
        "sessions_count": 1,
        "average_session_minutes": 1.0,
        "reading_days": 1,
        "current_streak": 1,
        "longest_streak": 1
    },
    "daily_breakdown": [
        {
            "date": "2026-03-12",
            "reading_time_minutes": 1,
            "pages_read": 1,
            "sessions_count": 1
        }
    ],
    "books_breakdown": [
        {
            "book_id": "string",
            "title": "string",
            "reading_time_minutes": 1,
            "pages_read": 1,
            "sessions_count": 1
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Goals¶

GET /goals¶

List reading goals

Returns all reading goals for the user.

Query Parameters:

is_active (boolean) – Filter by active status
is_completed (boolean) – Filter by completion status

Example request:

GET /goals HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of goals

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "goals": [
        {
            "goal_id": "string",
            "title": "string",
            "description": "string",
            "goal_type": "books_count",
            "target_value": 1,
            "current_value": 1,
            "progress_percentage": 1.0,
            "time_period": "daily",
            "start_date": "2026-03-12",
            "end_date": "2026-03-12",
            "is_active": true,
            "is_completed": true,
            "completed_at": "2026-03-12T10:47:30.995488",
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /goals¶

Create reading goal

Creates a new reading goal.

Example request:

POST /goals HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "description": "string",
    "goal_type": "books_count",
    "target_value": 1,
    "time_period": "daily",
    "start_date": "2026-03-12",
    "end_date": "2026-03-12"
}

Status Codes:

Goal created

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "goal_id": "string",
    "title": "string",
    "description": "string",
    "goal_type": "books_count",
    "target_value": 1,
    "current_value": 1,
    "progress_percentage": 1.0,
    "time_period": "daily",
    "start_date": "2026-03-12",
    "end_date": "2026-03-12",
    "is_active": true,
    "is_completed": true,
    "completed_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /goals/{goal_id}¶

Get goal details

Returns detailed information about a goal.

Parameters:

goal_id (string) – Goal ID

Example request:

GET /goals/{goal_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Goal details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "goal_id": "string",
    "title": "string",
    "description": "string",
    "goal_type": "books_count",
    "target_value": 1,
    "current_value": 1,
    "progress_percentage": 1.0,
    "time_period": "daily",
    "start_date": "2026-03-12",
    "end_date": "2026-03-12",
    "is_active": true,
    "is_completed": true,
    "completed_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /goals/{goal_id}¶

Update goal

Updates goal properties.

Parameters:

goal_id (string) – Goal ID

Example request:

PATCH /goals/{goal_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "title": "string",
    "description": "string",
    "target_value": 1,
    "end_date": "2026-03-12",
    "is_active": true
}

Status Codes:

200 OK –

Goal updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "goal_id": "string",
    "title": "string",
    "description": "string",
    "goal_type": "books_count",
    "target_value": 1,
    "current_value": 1,
    "progress_percentage": 1.0,
    "time_period": "daily",
    "start_date": "2026-03-12",
    "end_date": "2026-03-12",
    "is_active": true,
    "is_completed": true,
    "completed_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /goals/{goal_id}¶

Delete goal

Deletes a reading goal.

Parameters:

goal_id (string) – Goal ID

Status Codes:

204 No Content – Goal deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /goals/{goal_id}/progress¶

Update goal progress

Manually updates the current progress value.

Parameters:

goal_id (string) – Goal ID

Example request:

PUT /goals/{goal_id}/progress HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "current_value": 1,
    "note": "string"
}

Status Codes:

200 OK –

Progress updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "goal_id": "string",
    "title": "string",
    "description": "string",
    "goal_type": "books_count",
    "target_value": 1,
    "current_value": 1,
    "progress_percentage": 1.0,
    "time_period": "daily",
    "start_date": "2026-03-12",
    "end_date": "2026-03-12",
    "is_active": true,
    "is_completed": true,
    "completed_at": "2026-03-12T10:47:30.995488",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Sync¶

GET /sync/changes¶

Get changes since timestamp

Returns all changes since the specified timestamp. Used for incremental synchronization.

Query Parameters:

since (string) – Timestamp to get changes since (Required)
entity_types (array) – Filter by entity types

Example request:

GET /sync/changes?since=2026-03-12T10%3A47%3A30.995488 HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of changes

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "changes": [
        {
            "entity_type": "string",
            "entity_id": "string",
            "operation": "create",
            "data": {},
            "version": 1,
            "updated_at": "2026-03-12T10:47:30.995488",
            "device_id": "string"
        }
    ],
    "server_timestamp": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /sync/changes¶

Push local changes

Pushes local changes to the server. Handles conflict resolution automatically.

Example request:

POST /sync/changes HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "changes": [
        {
            "entity_type": "string",
            "entity_id": "string",
            "operation": "create",
            "data": {},
            "timestamp": "2026-03-12T10:47:30.995488",
            "version": 1
        }
    ],
    "device_id": "string"
}

Status Codes:

200 OK –

Changes applied

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "accepted": [
        {
            "entity_type": "string",
            "entity_id": "string",
            "new_version": 1
        }
    ],
    "rejected": [
        {
            "entity_type": "string",
            "entity_id": "string",
            "reason": "string"
        }
    ],
    "server_timestamp": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Conflict detected

Example response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "conflicts": [
        {
            "entity_type": "string",
            "entity_id": "string",
            "local_version": 1,
            "server_version": 1,
            "server_data": {},
            "resolved_data": {},
            "resolution_strategy": "latest_wins"
        }
    ]
}

GET /sync/status¶

Get sync status

Returns the current synchronization status.

Example request:

GET /sync/status HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Sync status

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "idle",
    "last_sync_at": "2026-03-12T10:47:30.995488",
    "pending_changes": 1,
    "error_message": "string"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /users/me/metadata-server¶

Get metadata server configuration

Returns the current metadata server connection configuration.

Example request:

GET /users/me/metadata-server HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Metadata server configuration

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "config_id": "string",
    "server_url": "https://example.com",
    "server_type": "official",
    "is_connected": true,
    "sync_enabled": true,
    "sync_interval_seconds": 1,
    "last_sync_at": "2026-03-12T10:47:30.995488",
    "sync_status": "idle",
    "sync_error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

No metadata server configured (local-only mode)

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PUT /users/me/metadata-server¶

Configure metadata server connection

Sets up connection to a metadata server for cross-device sync. Replaces any existing configuration.

Example request:

PUT /users/me/metadata-server HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "server_url": "https://example.com",
    "server_type": "official",
    "sync_enabled": true,
    "sync_interval_seconds": 1,
    "auth_token": "string"
}

Status Codes:

200 OK –

Configuration saved

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "config_id": "string",
    "server_url": "https://example.com",
    "server_type": "official",
    "is_connected": true,
    "sync_enabled": true,
    "sync_interval_seconds": 1,
    "last_sync_at": "2026-03-12T10:47:30.995488",
    "sync_status": "idle",
    "sync_error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /users/me/metadata-server¶

Disconnect from metadata server

Removes metadata server configuration and switches to local-only mode. Local data is preserved but will no longer sync.

Status Codes:

204 No Content – Disconnected from metadata server

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /users/me/metadata-server/test¶

Test metadata server connection

Tests connectivity to the configured metadata server.

Status Codes:

200 OK –

Connection test result

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true,
    "message": "string",
    "server_version": "string",
    "latency_ms": 1
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

No metadata server configured

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Storage¶

GET /storage/backends¶

List storage backends

Returns all configured file storage backends.

Example request:

GET /storage/backends HTTP/1.1
Host: example.com

Status Codes:

200 OK –

List of storage backends

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backends": [
        {
            "backend_id": "string",
            "backend_type": "local",
            "name": "string",
            "is_primary": true,
            "is_active": true,
            "base_path": "string",
            "storage_used_bytes": 1,
            "storage_quota_bytes": 1,
            "last_accessed_at": "2026-03-12T10:47:30.995488",
            "connection_status": "connected",
            "error_message": "string",
            "created_at": "2026-03-12T10:47:30.995488",
            "updated_at": "2026-03-12T10:47:30.995488"
        }
    ]
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /storage/backends¶

Add storage backend

Configures a new file storage backend.

Example request:

POST /storage/backends HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "backend_type": "local",
    "name": "string",
    "is_primary": true,
    "connection_config": {},
    "credentials": {},
    "base_path": "string"
}

Status Codes:

Backend configured

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "backend_id": "string",
    "backend_type": "local",
    "name": "string",
    "is_primary": true,
    "is_active": true,
    "base_path": "string",
    "storage_used_bytes": 1,
    "storage_quota_bytes": 1,
    "last_accessed_at": "2026-03-12T10:47:30.995488",
    "connection_status": "connected",
    "error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /storage/backends/{backend_id}¶

Get storage backend details

Returns information about a storage backend.

Parameters:

backend_id (string)

Example request:

GET /storage/backends/{backend_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Backend details

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backend_id": "string",
    "backend_type": "local",
    "name": "string",
    "is_primary": true,
    "is_active": true,
    "base_path": "string",
    "storage_used_bytes": 1,
    "storage_quota_bytes": 1,
    "last_accessed_at": "2026-03-12T10:47:30.995488",
    "connection_status": "connected",
    "error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

PATCH /storage/backends/{backend_id}¶

Update storage backend

Updates storage backend configuration.

Parameters:

backend_id (string)

Example request:

PATCH /storage/backends/{backend_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "is_active": true,
    "connection_config": {},
    "credentials": {},
    "base_path": "string"
}

Status Codes:

200 OK –

Backend updated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backend_id": "string",
    "backend_type": "local",
    "name": "string",
    "is_primary": true,
    "is_active": true,
    "base_path": "string",
    "storage_used_bytes": 1,
    "storage_quota_bytes": 1,
    "last_accessed_at": "2026-03-12T10:47:30.995488",
    "connection_status": "connected",
    "error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /storage/backends/{backend_id}¶

Remove storage backend

Removes a storage backend configuration. Does not delete files from the backend.

Parameters:

backend_id (string)

Status Codes:

204 No Content – Backend removed

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /storage/backends/{backend_id}/test¶

Test storage backend connection

Tests connectivity to the storage backend.

Parameters:

backend_id (string)

Status Codes:

200 OK –

Connection test result

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true,
    "message": "string",
    "storage_info": {
        "used_bytes": 1,
        "quota_bytes": 1
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /storage/backends/{backend_id}/set-primary¶

Set as primary backend

Sets this backend as the primary for new uploads.

Parameters:

backend_id (string)

Status Codes:

200 OK –

Primary backend set

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backend_id": "string",
    "backend_type": "local",
    "name": "string",
    "is_primary": true,
    "is_active": true,
    "base_path": "string",
    "storage_used_bytes": 1,
    "storage_quota_bytes": 1,
    "last_accessed_at": "2026-03-12T10:47:30.995488",
    "connection_status": "connected",
    "error_message": "string",
    "created_at": "2026-03-12T10:47:30.995488",
    "updated_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Files¶

POST /files/upload¶

Upload a book file

Uploads a book file to the primary storage backend. Returns file metadata after successful upload.

Status Codes:

File uploaded

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "file_path": "string",
    "file_format": "string",
    "file_size": 1,
    "file_hash": "string",
    "storage_backend_id": "string",
    "uploaded_at": "2026-03-12T10:47:30.995488"
}

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

413 Request Entity Too Large –

File too large

Example response:

HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

415 Unsupported Media Type –

Unsupported file format

Example response:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

GET /books/{book_id}/file¶

Get book file download URL

Returns a signed URL to download the book file. URL is valid for a limited time.

Parameters:

book_id (string) – Book ID

Example request:

GET /books/{book_id}/file HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Download URL

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "download_url": "https://example.com",
    "expires_at": "2026-03-12T10:47:30.995488"
}

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

DELETE /books/{book_id}/file¶

Delete book file

Deletes the book file from storage.

Parameters:

book_id (string) – Book ID

Status Codes:

204 No Content – File deleted

Authentication required

Example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

Resource not found

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}

POST /export/books¶

Export book files

Exports book files as a ZIP archive. Only includes files stored on the server.

Example request:

POST /export/books HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "book_ids": [
        "string"
    ],
    "include_metadata": true
}

Status Codes:

200 OK – ZIP archive

Validation error

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "code": "string",
        "message": "string",
        "details": {}
    }
}