Tome

https://tome.bndct.sh/docs
Admin
Tome is a self-hosted ebook and comic library server that connects to e-readers like KOReader to...
Tokens:17,552
Snippets:301
Trust Score:2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manually install TomeSync plugin

Source: https://tome.bndct.sh/docs/koreader

Commands to install the plugin on macOS or Linux systems.

```bash
cd ~/.koreader/plugins
cp ~/Downloads/tomesync.koplugin.zip .
unzip tomesync.koplugin.zip
```

--------------------------------

### Install Scribe Skill

Source: https://tome.bndct.sh/docs/scribe

Run the installation script within the local Tome checkout to symlink the skill for Claude Code.

```bash
# In your local Tome checkout:
./skills/scribe/install.sh

# That symlinks skills/scribe into ~/.claude/skills/scribe so Claude Code
# picks up the /scribe slash command on next launch.
```

--------------------------------

### Quick-start Installation Script

Source: https://tome.bndct.sh/docs/installation

Executes a shell script to automatically set up a temporary Tome instance for testing.

```bash
curl -fsSL https://tome.bndct.sh/install.sh | bash
```

--------------------------------

### GET /api/users

Source: https://tome.bndct.sh/docs/api

Lists all users in the system.

```APIDOC
## GET /api/users

### Description
Lists all users in the system.

### Method
GET

### Endpoint
/api/users
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://tome.bndct.sh/docs/installation

Example configuration for exposing Tome via Caddy.

```caddy
tome.example.com {
    reverse_proxy localhost:8080
}
```

--------------------------------

### GET /api/auth/me

Source: https://tome.bndct.sh/docs/api

Verifies the current authentication token.

```APIDOC
## GET /api/auth/me

### Description
Verifies the current authentication token.

### Method
GET

### Endpoint
/api/auth/me
```

--------------------------------

### GET /api/book-types

Source: https://tome.bndct.sh/docs/api

List all book types.

```APIDOC
## GET /api/book-types

### Description
List all book types.

### Method
GET

### Endpoint
/api/book-types
```

--------------------------------

### GET /api/tome-sync/position/{book_id}

Source: https://tome.bndct.sh/docs/api

Get reading position for a book.

```APIDOC
## GET /api/tome-sync/position/{book_id}

### Description
Get reading position for a book.

### Method
GET

### Endpoint
/api/tome-sync/position/{book_id}
```

--------------------------------

### GET /api/tome-sync/series

Source: https://tome.bndct.sh/docs/api

List series available for download.

```APIDOC
## GET /api/tome-sync/series

### Description
List series available for download.

### Method
GET

### Endpoint
/api/tome-sync/series
```

--------------------------------

### GET /api/home/forgotten-books

Source: https://tome.bndct.sh/docs/api

Retrieves a list of books that were started but have not been interacted with recently.

```APIDOC
## GET /api/home/forgotten-books

### Description
Retrieves a list of books that were started but have not been interacted with recently.

### Method
GET

### Endpoint
/api/home/forgotten-books
```

--------------------------------

### GET /api/home/activity

Source: https://tome.bndct.sh/docs/api

Retrieves a list of recent reading activity.

```APIDOC
## GET /api/home/activity

### Description
Retrieves a list of recent reading activity.

### Method
GET

### Endpoint
/api/home/activity
```

--------------------------------

### GET /api/libraries

Source: https://tome.bndct.sh/docs/api

List libraries visible to the current user.

```APIDOC
## GET /api/libraries

### Description
List libraries visible to current user.

### Method
GET

### Endpoint
/api/libraries
```

--------------------------------

### GET /api/admin/stats

Source: https://tome.bndct.sh/docs/api

Retrieves system-wide reading statistics.

```APIDOC
## GET /api/admin/stats

### Description
Retrieves system-wide reading statistics.

### Method
GET

### Endpoint
/api/admin/stats
```

--------------------------------

### GET /api/tome-sync/download/{book_id}/{file_id}

Source: https://tome.bndct.sh/docs/api

Download file (KOReader format).

```APIDOC
## GET /api/tome-sync/download/{book_id}/{file_id}

### Description
Download file (KOReader format).

### Method
GET

### Endpoint
/api/tome-sync/download/{book_id}/{file_id}
```

--------------------------------

### GET /api/admin/duplicates

Source: https://tome.bndct.sh/docs/api

Detects duplicate books in the library.

```APIDOC
## GET /api/admin/duplicates

### Description
Detects duplicate books in the library.

### Method
GET

### Endpoint
/api/admin/duplicates
```

--------------------------------

### GET /api/admin/audit-logs

Source: https://tome.bndct.sh/docs/api

Retrieves audit log entries.

```APIDOC
## GET /api/admin/audit-logs

### Description
Retrieves audit log entries.

### Method
GET

### Endpoint
/api/admin/audit-logs
```

--------------------------------

### GET /api/tome-sync/resolve

Source: https://tome.bndct.sh/docs/api

Resolve a file hash to a canonical book ID.

```APIDOC
## GET /api/tome-sync/resolve

### Description
Resolve a file hash to a canonical book ID.

### Method
GET

### Endpoint
/api/tome-sync/resolve
```

--------------------------------

### GET /api/books

Source: https://tome.bndct.sh/docs/api

Lists books in the library with optional filtering.

```APIDOC
## GET /api/books

### Description
List books in the library. Supports filtering via query parameters.

### Method
GET

### Endpoint
/api/books

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query
- **series** (string) - Optional - Filter by series
- **author** (string) - Optional - Filter by author
- **library_id** (string) - Optional - Filter by library ID
- **per_page** (integer) - Optional - Results per page
```

--------------------------------

### GET /api/stats/completion-estimates

Source: https://tome.bndct.sh/docs/stats

Retrieves projected finish dates for in-progress books.

```APIDOC
## GET /api/stats/completion-estimates

### Description
Retrieves projected finish dates for in-progress books.

### Method
GET

### Endpoint
/api/stats/completion-estimates
```

--------------------------------

### GET /api/saved-filters

Source: https://tome.bndct.sh/docs/api

List current user's shelves.

```APIDOC
## GET /api/saved-filters

### Description
List current user's shelves.

### Method
GET

### Endpoint
/api/saved-filters
```

--------------------------------

### GET /api/books/{id}

Source: https://tome.bndct.sh/docs/api

Retrieves detailed information about a specific book.

```APIDOC
## GET /api/books/{id}

### Description
Retrieve book detail including files, tags, and libraries.

### Method
GET

### Endpoint
/api/books/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the book
```

--------------------------------

### GET /api/stats

Source: https://tome.bndct.sh/docs/stats

Retrieves the main bundle of statistics for a specified number of days.

```APIDOC
## GET /api/stats

### Description
Retrieves the main bundle of statistics for the specified timeframe.

### Method
GET

### Endpoint
/api/stats

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to include in the stats.
- **tz_offset** (integer) - Optional - Timezone offset in minutes.
```

--------------------------------

### GET /api/stats/timeline

Source: https://tome.bndct.sh/docs/stats

Retrieves lifetime per-book reading spans and active days.

```APIDOC
## GET /api/stats/timeline

### Description
Retrieves lifetime per-book reading spans and active days.

### Method
GET

### Endpoint
/api/stats/timeline
```

--------------------------------

### GET /api/home/stats

Source: https://tome.bndct.sh/docs/api

Retrieves dashboard summary information including reading streak, pages read, and total reading time.

```APIDOC
## GET /api/home/stats

### Description
Retrieves dashboard summary information including reading streak, pages read, and total reading time.

### Method
GET

### Endpoint
/api/home/stats
```

--------------------------------

### POST /api/libraries

Source: https://tome.bndct.sh/docs/api

Create a new library.

```APIDOC
## POST /api/libraries

### Description
Create library (name, icon, is_public).

### Method
POST

### Endpoint
/api/libraries
```

--------------------------------

### Docker Compose Configuration

Source: https://tome.bndct.sh/docs/installation

Standard configuration for running Tome with persistent volumes for data, books, and the bindery.

```yaml
services:
  tome:
    image: ghcr.io/bndct-devops/tome:latest
    container_name: tome
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
      - ./books:/books
      - ./bindery:/bindery
    environment:
      # Optional. Auto-generated if unset — see /docs/configuration
      # - TOME_SECRET_KEY=
      # Optional. Better metadata. Get a free token at hardcover.app
      # - TOME_HARDCOVER_TOKEN=
    restart: unless-stopped
```

--------------------------------

### POST /api/books/reorganize

Source: https://tome.bndct.sh/docs/api

Moves files to their canonical paths.

```APIDOC
## POST /api/books/reorganize

### Description
Moves files to their canonical paths.

### Method
POST

### Endpoint
/api/books/reorganize
```

--------------------------------

### Configure SMTP environment variables

Source: https://tome.bndct.sh/docs/send-to-device

Set these environment variables on the server to enable the Send to device feature. The feature is active once host, user, and password variables are provided.

```text
TOME_SMTP_HOST=smtp.fastmail.com
TOME_SMTP_PORT=587
TOME_SMTP_USER=you@fastmail.com
TOME_SMTP_PASSWORD=your-app-password
```

```text
TOME_SMTP_HOST=smtp.gmail.com
TOME_SMTP_PORT=587
TOME_SMTP_USER=you@gmail.com
TOME_SMTP_PASSWORD=your-app-password
```

```text
TOME_SMTP_HOST=smtp.example.com
TOME_SMTP_PORT=587
TOME_SMTP_USER=tome@example.com
TOME_SMTP_PASSWORD=secret
TOME_SMTP_FROM=tome@example.com   # optional, defaults to TOME_SMTP_USER
```

--------------------------------

### Configure Bindery for Manual Review

Source: https://tome.bndct.sh/docs/bindery

The default configuration for the Tome service, requiring manual intervention for file ingestion.

```yaml
# docker-compose.yml — manual review (default)
services:
  tome:
    image: ghcr.io/bndct-devops/tome:latest
    volumes:
      - ./data:/data
      - ./books:/books
      - ./bindery:/bindery   # ← drop files here
    # No TOME_AUTO_IMPORT — manual is the default
```

--------------------------------

### Configure Tome OIDC Environment Variables

Source: https://tome.bndct.sh/docs/sso

Set these environment variables on the Tome container to enable OIDC authentication. Ensure the container is restarted after applying these changes.

```bash
TOME_OIDC_ENABLED=true
TOME_OIDC_ISSUER=https://auth.example.com
TOME_OIDC_CLIENT_ID=<from your IdP>
TOME_OIDC_CLIENT_SECRET=<from your IdP>
TOME_OIDC_ADMIN_GROUP=tome_admins
TOME_OIDC_MEMBER_GROUP=tome_members
TOME_OIDC_DEFAULT_ROLE=guest
# Behind a reverse proxy, pin your public origin so the redirect is correct:
TOME_PUBLIC_URL=https://tome.example.com
```

--------------------------------

### Verify Authentication Token

Source: https://tome.bndct.sh/docs/api

Use this command to validate that your bearer token is correctly configured for API access.

```bash
curl -H "Authorization: Bearer $TOKEN" https://your-tome/api/auth/me
```

--------------------------------

### POST /api/book-types

Source: https://tome.bndct.sh/docs/api

Create a book type.

```APIDOC
## POST /api/book-types

### Description
Create book type (admin).

### Method
POST

### Endpoint
/api/book-types
```

--------------------------------

### GET /api/stats/sessions

Source: https://tome.bndct.sh/docs/stats

Retrieves a paged list of reading sessions.

```APIDOC
## GET /api/stats/sessions

### Description
Retrieves a paged session list, oldest first.

### Method
GET

### Endpoint
/api/stats/sessions
```

--------------------------------

### POST /api/tome-sync/session

Source: https://tome.bndct.sh/docs/api

Record a reading session.

```APIDOC
## POST /api/tome-sync/session

### Description
Record a reading session.

### Method
POST

### Endpoint
/api/tome-sync/session
```

--------------------------------

### GET /api/books/library-health

Source: https://tome.bndct.sh/docs/api

Generates a report of misplaced files in the library.

```APIDOC
## GET /api/books/library-health

### Description
Generates a report of misplaced files in the library.

### Method
GET

### Endpoint
/api/books/library-health
```

--------------------------------

### POST /api/libraries/{id}/users

Source: https://tome.bndct.sh/docs/api

Assign a user to a library.

```APIDOC
## POST /api/libraries/{id}/users

### Description
Assign user to library (admin).

### Method
POST

### Endpoint
/api/libraries/{id}/users
```

--------------------------------

### POST /api/books/upload

Source: https://tome.bndct.sh/docs/api

Uploads a new book file to the library.

```APIDOC
## POST /api/books/upload

### Description
Upload a file to the library. Uses multipart form data.

### Method
POST

### Endpoint
/api/books/upload

### Parameters
#### Request Body
- **file** (file) - Required - The book file to upload
- **book_type_id** (string) - Optional - The type ID for the book
```

--------------------------------

### Configure Homepage dashboard widget for Tome

Source: https://tome.bndct.sh/docs/api-tokens

Integrate Tome reading statistics into a Homepage dashboard using the customapi widget.

```yaml
- Tome:
    icon: mdi-book-open-page-variant
    href: https://your-tome.example.com
    widget:
      type: customapi
      url: https://your-tome.example.com/api/home/stats
      headers:
        Authorization: Bearer tome_xxxxxxxx
      mappings:
        - field: current_streak_days
          label: Streak
          suffix: " days"
        - field: books_finished_30d
          label: Finished (30d)
        - field: reading_seconds_30d
          label: Read (30d)
          format: duration
        - field: pages_turned_30d
          label: Pages (30d)
```

--------------------------------

### POST /api/users

Source: https://tome.bndct.sh/docs/api

Creates a new user.

```APIDOC
## POST /api/users

### Description
Creates a new user.

### Method
POST

### Endpoint
/api/users
```

--------------------------------

### Promote User to Admin via Database

Source: https://tome.bndct.sh/docs/troubleshooting

Directly update a user's role to admin in the database to regain access to restricted features.

```bash
docker exec -it tome sqlite3 /data/tome.db "UPDATE users SET role='admin', is_admin=1 WHERE username='<username>';"
```

--------------------------------

### POST /api/auth/login

Source: https://tome.bndct.sh/docs/api

Authenticates the user and returns a JWT.

```APIDOC
## POST /api/auth/login

### Description
Authenticate the user and return a JWT for subsequent requests.

### Method
POST

### Endpoint
/api/auth/login
```

--------------------------------

### POST /api/books/purge-empty-dirs

Source: https://tome.bndct.sh/docs/api

Cleans up empty directories in the library.

```APIDOC
## POST /api/books/purge-empty-dirs

### Description
Cleans up empty directories in the library.

### Method
POST

### Endpoint
/api/books/purge-empty-dirs
```

--------------------------------

### POST /api/libraries/{id}/books

Source: https://tome.bndct.sh/docs/api

Add books to a library.

```APIDOC
## POST /api/libraries/{id}/books

### Description
Add books to library.

### Method
POST

### Endpoint
/api/libraries/{id}/books

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the library.

#### Request Body
- **book_ids** (array) - Required - List of book IDs to add.
```

--------------------------------

### PUT /api/libraries/{id}

Source: https://tome.bndct.sh/docs/api

Update an existing library.

```APIDOC
## PUT /api/libraries/{id}

### Description
Update library.

### Method
PUT

### Endpoint
/api/libraries/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the library to update.
```

--------------------------------

### Update Tome Container

Source: https://tome.bndct.sh/docs/installation

Command to pull the latest image and restart the container while preserving data.

```bash
docker compose pull && docker compose up -d
```

--------------------------------

### Authenticate with API tokens using curl

Source: https://tome.bndct.sh/docs/api-tokens

Use the Authorization header with a Bearer token to authenticate API requests.

```bash
# Replace TOKEN with your tome_… secret
curl -H "Authorization: Bearer $TOKEN" \
     https://your-tome.example.com/api/books?limit=5
```

--------------------------------

### Configure Scribe Authentication

Source: https://tome.bndct.sh/docs/scribe

Define API tokens and base URLs for different Tome instances in the scribe.json configuration file.

```json
# ~/.config/tome/scribe.json — multi-profile config
{
  "profiles": {
    "dev": {
      "base_url": "http://localhost:8080",
      "token":    "tome_dev_…"
    },
    "prod": {
      "base_url": "https://tome.example.com",
      "token":    "tome_prod_…"
    }
  },
  "default": "dev"
}
```

--------------------------------

### POST /api/users/{id}/impersonate

Source: https://tome.bndct.sh/docs/api

Impersonates a user and returns their JWT.

```APIDOC
## POST /api/users/{id}/impersonate

### Description
Impersonates a user and returns their JWT.

### Method
POST

### Endpoint
/api/users/{id}/impersonate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.
```

--------------------------------

### Catppuccin Mocha Color Palette

Source: https://tome.bndct.sh/docs/themes

Hex values for the Catppuccin Mocha theme configuration.

```text
#1E1E2E, #CDD6F4, #313244, #CBA6F7, #1E1E2E, #45475A, #A6ADC8, #B4BEFE, #45475A, #F38BA8
```

--------------------------------

### PUT /api/saved-filters/{id}

Source: https://tome.bndct.sh/docs/api

Update shelf name or icon.

```APIDOC
## PUT /api/saved-filters/{id}

### Description
Update shelf name / icon.

### Method
PUT

### Endpoint
/api/saved-filters/{id}
```

--------------------------------

### Nord Color Palette

Source: https://tome.bndct.sh/docs/themes

Hex values for the Nord theme configuration.

```text
#2E3440, #D8DEE9, #3B4252, #88C0D0, #2E3440, #4C566A, #D8DEE9, #81A1C1, #4C566A, #BF616A
```

--------------------------------

### POST /api/admin/duplicates/dismiss

Source: https://tome.bndct.sh/docs/api

Dismisses a duplicate book pair.

```APIDOC
## POST /api/admin/duplicates/dismiss

### Description
Dismisses a duplicate book pair.

### Method
POST

### Endpoint
/api/admin/duplicates/dismiss
```

--------------------------------

### PUT /api/tome-sync/position/{book_id}

Source: https://tome.bndct.sh/docs/api

Update reading position.

```APIDOC
## PUT /api/tome-sync/position/{book_id}

### Description
Update reading position.

### Method
PUT

### Endpoint
/api/tome-sync/position/{book_id}
```

--------------------------------

### POST /api/admin/duplicates/merge

Source: https://tome.bndct.sh/docs/api

Merges a pair of duplicate books.

```APIDOC
## POST /api/admin/duplicates/merge

### Description
Merges a pair of duplicate books.

### Method
POST

### Endpoint
/api/admin/duplicates/merge
```

--------------------------------

### PUT /api/book-types/{id}

Source: https://tome.bndct.sh/docs/api

Update a book type.

```APIDOC
## PUT /api/book-types/{id}

### Description
Update book type.

### Method
PUT

### Endpoint
/api/book-types/{id}
```

--------------------------------

### DELETE /api/libraries/{id}/books/{book_id}

Source: https://tome.bndct.sh/docs/api

Remove a book from a library.

```APIDOC
## DELETE /api/libraries/{id}/books/{book_id}

### Description
Remove book from library.

### Method
DELETE

### Endpoint
/api/libraries/{id}/books/{book_id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the library.
- **book_id** (string) - Required - The ID of the book to remove.
```

--------------------------------

### PUT /api/books/{id}/status

Source: https://tome.bndct.sh/docs/api

Updates the reading status and progress for a book.

```APIDOC
## PUT /api/books/{id}/status

### Description
Set the reading status, progress, and CFI for a specific book.

### Method
PUT

### Endpoint
/api/books/{id}/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the book
```

--------------------------------

### DELETE /api/libraries/{id}/users/{user_id}

Source: https://tome.bndct.sh/docs/api

Remove a user from a library.

```APIDOC
## DELETE /api/libraries/{id}/users/{user_id}

### Description
Remove user from library (admin).

### Method
DELETE

### Endpoint
/api/libraries/{id}/users/{user_id}
```

--------------------------------

### Dashboard Management

Source: https://tome.bndct.sh/docs/stats

Endpoints for retrieving and updating saved dashboard layouts.

```APIDOC
## GET /api/stats/dashboard

### Description
Retrieves saved dashboard layouts.

### Method
GET

### Endpoint
/api/stats/dashboard

## PUT /api/stats/dashboard

### Description
Updates saved dashboard layouts.

### Method
PUT

### Endpoint
/api/stats/dashboard
```

--------------------------------

### POST /api/saved-filters

Source: https://tome.bndct.sh/docs/api

Save current filter params as a shelf.

```APIDOC
## POST /api/saved-filters

### Description
Save current filter params as a shelf.

### Method
POST

### Endpoint
/api/saved-filters
```
Tokens:
Raw