canonical: https://jentic.com/apis/kavitareader.com/kavita

# Kavitareader Kavita

Jentic publishes the only available OpenAPI specification for Kavita, keeping it validated and agent-ready. Kavita is a self-hosted ebook, comic, and manga reader server that exposes a large REST surface (493 endpoints) for managing libraries, series, chapters, collections, want-to-read lists, reading progress, devices, OPDS feeds, scrobbling, and admin operations. The base URL is parameterised because Kavita is self-hosted: clients point at their own server instance. Authentication uses an API key passed in the `x-api-key` header, with JWT-based session tokens layered on top for browser users.

## For AI agents

Manage a self-hosted Kavita library server: search and read series, chapters, collections, reading progress, want-to-read lists, devices, and admin settings. 493 endpoints covering the full reading platform.

## Scope

Does not handle audiobook playback, video streaming, or DRM-protected commercial ebook stores - use for managing a self-hosted Kavita ebook, comic, and manga library only.

## Capabilities

- Browse and search series, chapters, and collections via `/api/Series`, `/api/Chapter`, and `/api/Collection` endpoints
- Track and update reading progress, marks, and resume points via reader and account endpoints
- Manage personal want-to-read and reading-list curation through `/api/WantToRead` and related endpoints
- Administer libraries, scan jobs, and metadata refresh via the `/api/Admin` and `/api/Library` endpoints
- Stream chapter pages and download files for offline reading via `/api/Download` endpoints
- Configure devices, email delivery, and OPDS feeds for ereader clients

## Use cases

### Personal Library Reading Automation

Power a personal home-server reading workflow: when a new chapter is added to a tracked series, mark it as want-to-read, push a notification, and queue a download to a Kindle. Kavita's endpoints expose every piece of state needed (series, chapters, want-to-read, devices) so a small automation can keep a household's reading queue moving without anyone touching the web UI.

Example prompt: List unread chapters in series {id} via `/api/Series/{id}` and add the next one to the want-to-read list via the `/api/WantToRead` endpoint.

### Reading Progress Sync Across Devices

Keep reading progress in sync between a phone, laptop, and dedicated ereader by pushing progress events to Kavita and reading them back from another device. The reader endpoints store per-chapter progress with timestamp, page, and percent-read, which is the canonical state Kavita's official clients use; third-party readers can mirror that behaviour via the API.

Example prompt: Update progress for chapter {id} to page 84 via the reader progress endpoint, then read it back from another client.

### Library Maintenance and Metadata Refresh

Run library scans and metadata refreshes on a schedule so newly downloaded files appear in Kavita without manual intervention. The `/api/Admin` and `/api/Library` endpoints expose scan triggers, last-scan timestamps, and metadata refresh operations, letting a cron-driven script do what otherwise requires an admin UI session.

Example prompt: Trigger a scan for library {id} via the `/api/Library` scan endpoint and poll for completion.

### OPDS and Email Delivery to Ereaders

Expose a curated reading list via OPDS so dedicated ereader apps can subscribe to a personal feed, or push selected chapters to a Kindle email address using Kavita's email delivery endpoints. The `/api/Email` and OPDS endpoints handle the protocol details so the user just clicks 'send to my Kindle' or subscribes their Moon+ Reader to a feed URL.

Example prompt: Trigger send-to-device for chapter {id} via the `/api/Email` endpoint targeting the user's saved Kindle address.

### Agent-Driven Reading Companion

A personal AI reading companion uses Jentic to query Kavita ('what should I read next?', 'mark today's chapter as read', 'add the new One Piece chapter to my list') and execute the calls. Jentic stores the x-api-key in its vault and points the parameterised base URL at the user's self-hosted server, so secrets never appear in chat with the agent.

Example prompt: Use the Jentic search 'mark a Kavita chapter as read', load the schema, and execute the call for chapter {id}.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/Account/login` | Log in and obtain a session token |
| POST | `/api/Account/refresh-token` | Refresh a session token |
| POST | `/api/Account/register` | Register a new user |
| GET | `/api/Account` | Return the current account profile |
| POST | `/api/Account/reset-password` | Reset a user's password |
| POST | `/api/Account/clear-oidc-link` | Clear an OIDC link from the account |

## Key resources

- **Series and Chapters** — Browse, search, and manage series and chapter metadata.
- **Collections and Reading Lists** — Curate collections, want-to-read, and reading-list entries per user.
- **Reader Progress** — Track and update per-chapter reading progress and bookmarks.
- **Library Admin** — Manage libraries, trigger scans, and refresh metadata.
- **Devices and Email** — Configure ereader devices and send-to-device email delivery.
- **OPDS and Download** — Publish OPDS feeds and download chapter files.

## Why Jentic

- **Setup:** Wiring the Kavita API by hand means learning its x-api-key header, pointing calls at your own self-hosted host, managing the JWT session, and finding the right route among hundreds yourself. Through Jentic you install once, import the Kavita API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Kavita spreads its work across many operations, so scope the agent by the ones it needs, such as reading account details or marking reading progress. You pick that set, so account operations like register or reset-password are not included unless you add them.
- **Credential handling:** Your Kavita API key and any JWT session token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'mark a Kavita chapter as read' or 'get my Kavita account', and Jentic returns the matching Kavita operation with its parameter schema so the agent calls the right endpoint without crawling the reference docs by hand.

## Related APIs

- **Plex API** — Self-hosted media server with limited ebook support compared with Kavita's deep manga and comic features.
- **Google Books API** — Catalogue lookups for series and book metadata Kavita does not have locally.
- **Spotify Web API** — Audiobook and podcast adjunct for content Kavita does not host.
- **SoundCloud API** — Audio content library that complements text-focused Kavita libraries.

## FAQ

### Why is there no official OpenAPI spec for Kavita?

The Kavita project does not ship a hosted OpenAPI specification for third-party consumption. Jentic generates and maintains this spec so that AI agents and developers can call Kavita via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Kavita API use?

The Kavita API uses an API key in the `x-api-key` header (the spec calls the scheme `AuthKey`). Browser clients can additionally exchange username and password at `/api/Account/login` for a JWT and refresh it via `/api/Account/refresh-token.` Through Jentic the API key is encrypted in the vault and injected at execution time.

### Can I track reading progress through the Kavita API?

Yes. Kavita exposes per-chapter reading progress endpoints under the reader resource that store page, percent-read, and timestamp. Updating progress from one client and reading it from another is the standard sync mechanism Kavita's official apps use.

### What are the rate limits for the Kavita API?

Because Kavita is self-hosted there is no vendor-imposed quota. Throughput is bounded by the user's server CPU, disk, and network. The endpoints are designed for a single household's traffic, so steady use from one or two automations is safely within capacity on a typical NAS or home server.

### How do I add a series to my want-to-read list through Jentic?

Run `pip install jentic` and search Jentic for 'add a series to Kavita want-to-read'. Jentic returns the schema for the `/api/WantToRead` endpoint; supply the series ID, then execute the call. The x-api-key is injected from your Jentic One instance.

### Does the Kavita API support OPDS for ereader apps?

Yes. Kavita publishes OPDS feeds that ereader apps (Moon+ Reader, KOReader, Aldiko) can subscribe to. The OPDS endpoints sit alongside the REST surface in the spec and authenticate with the same x-api-key value.

### Is the Kavita API free to use?

Yes - Kavita is open-source and free for personal use, and so is its API surface. The only cost is the server you run it on.

### Can I limit what my agent is allowed to do with the Kavita API?

Yes. Because you run Jentic One yourself, you decide which of Kavita's many operations the agent can call, so you can grant just the ones it needs, such as reading account details or marking reading progress, and leave the rest out. Sensitive account operations like register or reset-password are not available to the agent unless you explicitly add them. Your Kavita x-api-key and JWT session token are stored by your own instance and injected only when a permitted call runs, so the agent never sees the raw credentials.