Version: 1.11.1

Codex API

REST API for Codex, a digital library server for comics, manga, and ebooks.

Interactive API Documentation

You can explore and test this API interactively:

• Hosted Documentation: Visit codex.4sh.dev/docs/api for the full API reference
• Your Instance: If you have Scalar UI enabled, access /api/docs on your Codex server

Authentication

Most endpoints require authentication. Codex supports two authentication methods:

1. JWT Bearer Token: Obtain a token via POST /api/v1/auth/login, then include it as Authorization: Bearer <token>
2. API Key: Generate an API key in the web UI or via the API, then include it as X-API-Key: <key> header

OPDS Support

Codex provides OPDS catalog feeds for e-reader applications:

• OPDS 1.2 (Atom XML): /opds/v1/catalog - Compatible with most e-readers
• OPDS 2.0 (JSON): /opds/v2 - Modern JSON-based format with enhanced features

Komga-Compatible API

Codex provides an optional Komga-compatible API for third-party apps like Komic:

• Disabled by default - Enable via komga_api.enabled: true in config
• Configurable prefix - Default path: /{prefix}/api/v1/ where prefix defaults to komga
• Same authentication - Supports JWT, API keys, and Basic Auth

Note: The {prefix} path parameter in Komga endpoints is configurable at runtime.

Pagination

List endpoints support pagination with the following conventions:

Query Parameters

All endpoints (GET and POST) use query parameters for pagination:

Parameter	Default	Max	Description
page	1	-	Page number (1-indexed)
pageSize	50	500	Items per page

Example GET: GET /api/v1/books?page=2&pageSize=25

Example POST: POST /api/v1/series/list?page=1&pageSize=25&sort=name,asc

For POST endpoints like /api/v1/books/list and /api/v1/series/list:

• Pagination parameters (page, pageSize, sort) go in the query string
• Filter criteria (condition, fullTextSearch) go in the request body

Response Format

All paginated responses use camelCase and include HATEOAS navigation links:

{
  "data": [...],
  "page": 1,
  "pageSize": 25,
  "total": 150,
  "totalPages": 6,
  "links": {
    "self": "/api/v1/series/list?page=1&pageSize=25",
    "first": "/api/v1/series/list?page=1&pageSize=25",
    "next": "/api/v1/series/list?page=2&pageSize=25",
    "last": "/api/v1/series/list?page=6&pageSize=25"
  }
}

Rate Limiting

All API endpoints are protected by rate limiting (enabled by default). Rate limits use a token bucket algorithm with separate limits for anonymous and authenticated users.

Limits

Client Type	Requests/Second	Burst Size
Anonymous (by IP)	10	50
Authenticated (by user)	50	200

Response Headers

All responses include rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests allowed (burst size)
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Seconds until a token is available

429 Too Many Requests

When rate limited, the API returns HTTP 429 with a Retry-After header:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 30 seconds.",
  "retry_after": 30
}

Exempt Paths

The following paths are exempt from rate limiting:

• /health - Health check endpoint
• /api/v1/events - SSE event stream

Authentication

API Key: api_key

Security Scheme Type:	apiKey
Header parameter name:	X-API-Key

HTTP: Bearer Auth

JWT token obtained from /api/v1/auth/login

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

License

MIT