canonical: https://jentic.com/apis/mangadex.org/mangadex

# MangaDex API

The MangaDex API serves an ad-free manga reader: it exposes the full catalogue - manga, chapters, covers, authors, scanlation groups, custom lists, ratings, and the MangaDex@Home image delivery network - to client apps, recommendation tools, and reader bots. Coverage spans discovery (search and feeds), reading (chapter image URLs via at-home tokens), account features (follows, custom lists, ratings), and upload and moderation operations. Catalogue reads such as GET /manga, GET /chapter, and GET `/at-home/server/{chapterId}` declare no security in the spec; the account, upload, and moderation operations take a bearer token. The acceptable use policy requires crediting MangaDex and scanlation groups and forbids running ads or paid services on consumers of the API.

## For AI agents

Search the MangaDex catalogue and read manga chapters - including manga, chapter, cover, author, and scanlation group lookups plus the at-home image server - through a REST API whose catalogue reads are open and whose account operations take a bearer token.

## Scope

Does not handle Western comics, light novels, or paid distribution - use for manga catalogue search, chapter reading, and user lists only.

## Capabilities

- Search the manga catalogue by title, tag, or content rating with pagination
- Pull a manga's chapter feed in reading order across all available languages
- Resolve a chapter id to its at-home image server URLs for image delivery
- Manage a user's custom lists, follows, and per-manga ratings
- Look up authors, artists, and scanlation groups attached to a title

## Use cases

### Build a personal manga reader

A reader app for personal use needs to search the MangaDex catalogue, list chapters, and stream images legally through MangaDex's at-home network. GET /manga supports the search, GET `/manga/{id}/feed` returns the chapter list, and GET `/at-home/server/{chapterId}` returns the image hostnames and tokens that the reader uses to fetch pages. Crediting MangaDex and the scanlation group on each chapter is required by the acceptable use policy.

Example prompt: Given the manga id 'a1c7c817-4e59-43b7-9365-09675a149a6f', list the latest 5 English chapters and resolve the image URLs for the most recent one.

### Track new chapters for followed titles

A fan tracker watches a list of manga and notifies the user when new chapters drop. The follow list comes from GET `/user/follows/manga`, and per-title chapter feeds via GET `/manga/{id}/feed` reveal new chapters with their published-at timestamps. Cross-referencing against a stored last-seen timestamp produces the diff to notify on.

Example prompt: For each manga the user follows, fetch the chapter feed and return any chapters published since the last run.

### Recommendation surface for a fan site

Community fan sites use MangaDex's recommendation endpoint to surface 'if you liked X, try Y' panels next to a title page. GET `/manga/{id}/recommendation` returns related manga ids, which can then be hydrated with covers and titles via GET `/manga/{id}` and GET /cover. The result is a recommendation row built from MangaDex's own related-titles graph.

Example prompt: Given a manga id, fetch the top 6 recommended manga, hydrate each with title and cover URL, and return the list.

### Agent-driven manga discovery assistant

An AI assistant inside a chat or voice interface helps a user find their next read. Through Jentic, the agent searches by intent, calls /manga with the user's preferences (tags, content rating, status), and follows up with `/manga/{id}/recommendation.` The agent never holds the user's MangaDex bearer token directly - Jentic injects it at call time.

Example prompt: Given a user prompt 'recommend a completed romance manga rated safe', call MangaDex via Jentic and return three suggestions with titles, descriptions, and cover URLs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/manga` | Search the manga catalogue with filters |
| GET | `/manga/{id}` | Get a single manga by id |
| GET | `/manga/{id}/aggregate` | Get aggregated volume and chapter structure for a manga |
| GET | `/manga/{id}/recommendation` | Get recommended related manga |
| GET | `/chapter` | List and filter chapters across the catalogue |
| GET | `/at-home/server/{chapterId}` | Get the MangaDex@Home server URL and page filenames for a chapter |
| GET | `/ping` | Service health check |

## Key resources

- **Manga** — Catalogue records with titles, tags, status, and relationships
- **Chapter** — Per-chapter metadata, language, scanlation group, and pages
- **AtHome** — Token-based image server URLs for streaming chapter pages
- **Cover** — Cover art records linked to manga
- **Author** — Author and artist records with attributed manga
- **ScanlationGroup** — Groups that translate and upload chapters
- **CustomList** — User-curated lists of manga
- **Authentication** — Login, refresh, and logout endpoints, all marked deprecated in the spec

## Why Jentic

- **Setup:** Wiring MangaDex by hand means registering a personal API client in your account settings, exchanging its client id and secret plus your username and password at the OAuth2 token service on auth.mangadex.org for a short-lived access token, learning the /manga query conventions, and refreshing that token yourself. Through Jentic you install once, import the MangaDex API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The MangaDex endpoints your agent uses are catalogue reads, so scoping is by operation: you limit the agent to the operations it needs, such as searching manga, fetching a title, or getting its chapter aggregate, and leave out anything else. Only the operations you allow are reachable, so the agent stays inside that set.
- **Credential handling:** Your MangaDex credentials and bearer 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 'search the MangaDex catalogue' or 'get a title's chapters', and Jentic returns the matching MangaDex operation with its query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Comic Vine** — Comics catalogue API focused on Western comics rather than manga.
- **OpenAI** — Generate manga summaries, recommendations, or descriptions from MangaDex catalogue records.
- **Anthropic Messages** — Use Claude to write reading-list blurbs and tag explanations for MangaDex catalogue records.

## FAQ

### Is there an official OpenAPI spec for the MangaDex API?

Yes. MangaDex publishes an OpenAPI 3.0.3 specification at api.mangadex.org/docs/api.yaml, version 5.13.1. The spec in the Jentic API Directory is a copy of that same version: 80 paths and 113 operations, with none added or removed, so what your agent calls matches what MangaDex documents.

### What authentication does the MangaDex API use?

The spec declares an HTTP bearer scheme, required by 87 of its 113 operations. MangaDex issues those tokens from its OAuth2 service on auth.mangadex.org, using a personal client id and secret; an access token lasts 15 minutes and is renewed with the refresh token. The older POST `/auth/login` and POST `/auth/refresh` operations are marked deprecated in the spec. The remaining 26 operations need no credential, including catalogue reads such as GET /manga and GET /chapter. Through Jentic the credential is stored encrypted by your own Jentic One instance and injected at call time, so the agent never sees it.

### Can I read manga chapter images through the MangaDex API?

Yes, but image bytes are not served from api.mangadex.org. Call GET `/at-home/server/{chapterId}` to get a signed at-home server URL plus the chapter hash and page filenames; the client then fetches the image bytes from that at-home host. The acceptable use policy requires crediting MangaDex and the scanlation group when displaying chapters.

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

MangaDex documents a global limit of approximately 5 requests per second per IP address for api.mangadex.org as a whole, plus per-endpoint limits such as 40 per minute on GET `/at-home/server/{chapterId}.` Rate-limited responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Retry-After, the last being the UNIX timestamp for the end of the current period. Once above the limit, requests to mangadex.org return HTTP 429 until your rate falls back in line, and persisting triggers a temporary IP ban.

### How do I connect the MangaDex API to my agent through Jentic?

Install Jentic One on your own infrastructure, then tell your agent to add the MangaDex API from the Jentic API Directory. Your agent searches by intent, for example 'search the MangaDex catalogue', and Jentic returns the GET /manga operation with its query parameter schema (title, includedTags[], contentRating[], status[]) for the agent to execute. Get started with Jentic One, the self-hosted execution layer, at github.com/jentic/jentic-one.

### Are commercial uses of the MangaDex API allowed?

No. MangaDex's acceptable use policy forbids running ads or paid services on apps and sites that consume the API, and requires crediting MangaDex and scanlation groups. Build personal, fan, or non-commercial tools only.

### Is there a MangaDex MCP server?

You do not need an MCP server to give your agent the MangaDex API. Jentic connects it directly from the API Directory: import the API, store your credential once, and your agent calls it. Catalogue reads work unauthenticated, and the 87 operations that need a bearer token get it injected at call time by your own Jentic One instance.

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

Yes. Because you run Jentic One yourself, your own rules decide which MangaDex operations the agent may call, so you scope access per operation. You can allow only catalogue reads such as searching manga with GET /manga, fetching a title with GET `/manga/{id}`, or getting its chapter aggregate with GET `/manga/{id}/aggregate`, and leave the other endpoints out. The agent can only reach the operations you picked, and your MangaDex credentials stay with your own instance rather than the agent.