# AnimeDoc API — full reference > AnimeDoc is an anime and movie streaming API with search, details and playback endpoints, plus a free site to watch anime online. This file is the complete AnimeDoc API reference for developers and AI assistants. The short version is https://animedoc.cloud/llms.txt and the machine-readable spec is https://animedoc.cloud/openapi.json. ## Authentication (required) - Base URL: https://api.animedoc.cloud - Every catalog endpoint requires an API key in the `X-API-Key` header. Requests without one get HTTP 401. - Get a free key: create an account at https://animedoc.cloud/docs/pricing and press "Generate API key". It works immediately on the Free plan; paid plans raise the limits and add the Stream Proxy. - Keep the key on your server (environment variable such as ANIMEDOC_API_KEY). Don't put it in public frontend code: anyone who sees it can spend your quota. A browser app should call your own backend, which calls AnimeDoc. - Free endpoint index (no key needed): GET https://api.animedoc.cloud/api/v2/ ## Building a streaming site with AnimeDoc 1. Front page: GET /api/v2/anime/home/ returns banners and ready-made rows (most watched, latest anime, latest movies, popular, top rated, collections). For a page per category, GET /api/v2/anime/section/?id=anime (or movies, series, asian, bollywood, nollywood) returns featured titles with trailers and that section's rows. Or build rows yourself with /trending/ and /browse/. Every item includes "trailer" (a short MP4 URL, or empty) and "backdrop" (a landscape still) for hover previews. 2. Catalog pages: GET /api/v2/anime/browse/?channelId=2&genre=Anime&sort=Latest (channelId 1 = movies, 2 = series, 1006 = animation; sort Latest, Hottest or Rating; country India = Bollywood, Nigeria = Nollywood, Korea = K-drama, Japan, China, Thailand). 3. Search box: POST /api/v2/anime/suggest/ while typing, POST /api/v2/anime/search/ on submit. 4. Title page: GET /api/v2/anime/detail/?detailPath=... for the description, seasons (`se`) and episode counts (`maxEp`). A movie has a single season with se 0 and maxEp 0. 5. Player: GET /api/v2/anime/media-sources/?subjectId=...&detailPath=...&se=1&ep=1 for video URLs in several resolutions plus subtitles (pass se=0&ep=0 for movies). Play a URL through GET /api/v2/anime/stream-file/?video_url=... (paid plan) from your backend, forwarding the player's Range header so seeking works. 6. Continue watching, auto-next episode and quality selection are client-side: store the last se/ep/time per detailPath, go to ep+1 (or the next season) when the video ends, and switch between the resolutions Media Sources returns. ## Rate limits Each plan has a requests-per-day quota (resets 00:00 UTC) and a requests-per-minute limit. Over either one returns HTTP 429 with a Retry-After header. Response headers: - X-RateLimit-Limit: Requests allowed per day on your plan. - X-RateLimit-Remaining: Requests left today. - X-RateLimit-Reset: Unix time (seconds) when the daily quota resets, always 00:00 UTC. - X-RateLimit-Limit-Minute: Requests allowed per minute. - X-RateLimit-Remaining-Minute: Requests left in the current minute. ## Errors - 400 {"error": "Missing detailPath query parameter"}: A required parameter is missing or invalid. - 401 {"detail": "An API key is required. Send it as the X-API-Key header. ..."}: No X-API-Key header, or the key doesn't exist (Invalid API key). Every catalog endpoint needs a key; get a free one at /docs/pricing. - 403 {"detail": "Playback through the API needs a paid plan ..."}: Your plan doesn't include this endpoint. The stream proxy needs a paid plan. - 404 {"error": "No playable source is available ..."}: The title or episode doesn't exist, or has no playable source right now. - 429 {"error": "rate_limit_exceeded"} or {"error": "daily_quota_exceeded"}: Over your plan's requests per minute or per day. Wait Retry-After seconds, or upgrade. - 502 {"error": "...", "details": "..."}: The content provider didn't answer in time. Safe to retry with backoff. # Endpoints ## Home Feed GET https://api.animedoc.cloud/api/v2/anime/home/ Docs: https://animedoc.cloud/docs/endpoints/home Everything a streaming front page needs in one call: banners and ready-made catalog rows. Returns banners (featured titles with a wide backdrop image) and rows: Most watched today, Latest anime, Latest movies, Popular anime, New anime movies, Popular movies, Popular series, Top rated anime, Latest animation, then curated collections. Rows built from Browse include a browse object with the exact channelId/sort/genre to page through the full list. Items share one compact shape; pass detailPath to Details and subjectId + detailPath to Media Sources. Cached for 10 minutes. Parameters: - none Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/home/" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const res = await fetch("https://api.animedoc.cloud/api/v2/anime/home/", { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/home/", params={}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "banners": [ { "subjectId": "6377932688309244960", "subjectType": 2, "title": "The Terminal List S2", "detailPath": "the-terminal-list-YMJKCBXZ8B7", "cover": "https://pbcdn.aoneroom.com/image/...jpg?x-oss-process=image/resize,w_480", "backdrop": "https://pbcdn.aoneroom.com/image/...webp?x-oss-process=image/resize,w_1600", "genre": "Action,Drama,Thriller", "releaseDate": "2022-07-01", "rating": "7.9", "country": "United States", "description": "..." } ], "rows": [ { "id": "latest-anime", "title": "Latest anime", "browse": { "channelId": 2, "sort": "Latest", "genre": "Anime" }, "items": [ { "subjectId": "3325889774849773352", "subjectType": 2, "title": "Naruto", "detailPath": "naruto-2D7JgAQBGX3", "cover": "https://pbcdnw.aoneroom.com/image/.../naruto.jpg?x-oss-process=image/resize,w_360", "genre": "Anime,Action,Adventure", "releaseDate": "2005-09-10", "rating": "8.4", "country": "Japan" } ] } ] } } ``` ## Section GET https://api.animedoc.cloud/api/v2/anime/section/ Docs: https://animedoc.cloud/docs/endpoints/section A ready-made page for one section (anime, movies, series, asian, bollywood, nollywood), or that section's filtered list. With just id: featured (titles with trailers, for a header; anime uses what's popular this season), filters (the sort, kind, genre and year options that section supports), rows (each with the query behind it) and, for anime, upcoming (upcoming anime with a youtubeId trailer). Add any of sort, kind, genre, year or page to get that section's filtered list instead, as items + pager. Every result really belongs to the section: no non-anime in anime, no anime in movies, only Nigerian titles in nollywood, only Korean/Japanese/Chinese/Thai live-action in asian. Items include trailer (a short MP4, or empty) and backdrop (a landscape still) for hover previews. Parameters: - id (query, string, required): anime, movies, series, asian, bollywood or nollywood. - sort (query, string, default Hottest): Latest, Hottest or Rating (filtered list). - kind (query, string): series or movies, where the section has both (filtered list). - genre (query, string): One of the section's filters.genre values, e.g. Action (filtered list). - year (query, integer): Release year, e.g. 2026 (filtered list). - country (query, string): asian only: Korea, Japan, China or Thailand (filtered list). - page (query, integer, default 1): Page of the filtered list. Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/section/?id=anime" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const params = new URLSearchParams({"id":"anime"}); const res = await fetch("https://api.animedoc.cloud/api/v2/anime/section/?" + params, { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/section/", params={"id":"anime"}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "id": "anime", "title": "Anime", "tagline": "Latest episodes, all-time classics and new seasons", "featured": [ { "subjectId": "...", "title": "Black Clover [English]", "detailPath": "black-clover-english-...", "cover": "https://...jpg?x-oss-process=image/resize,w_360", "trailer": "https://macdn.aoneroom.com/media/...-sd.mp4", "backdrop": "https://...webp?x-oss-process=image/resize,w_960", "genre": "Anime,Action", "rating": "8.2" } ], "filters": { "sort": [{ "value": "Latest", "label": "Latest" }, { "value": "Hottest", "label": "Popular" }, { "value": "Rating", "label": "Top rated" }], "kind": ["series", "movies"], "genre": ["Action", "Adventure", "Comedy", "Drama", "Fantasy", "Romance"], "year": ["2026", "2025", "2024"] }, "rows": [ { "id": "season", "title": "Popular this season", "query": { "sort": "Hottest", "kind": "series", "genre": "", "year": "2026" }, "items": [] } ], "upcoming": [ { "title": "...", "cover": "https://...", "youtubeId": "abc123", "aired": "Jan 2027", "genre": "Action,Fantasy" } ] } } ``` ## Trending GET https://api.animedoc.cloud/api/v2/anime/trending/ Docs: https://animedoc.cloud/docs/endpoints/trending What most people are watching right now, across anime, movies and series. Pages start at 0. Use it for a "Most watched" or "Trending now" row. Same item shape as Search and Browse. Parameters: - page (query, integer, default 0): Page number, starting at 0. - perPage (query, integer, default 24): Items per page (max 48). Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/trending/?page=0&perPage=24" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const params = new URLSearchParams({"page":"0","perPage":"24"}); const res = await fetch("https://api.animedoc.cloud/api/v2/anime/trending/?" + params, { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/trending/", params={"page":0,"perPage":24}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "pager": { "page": 0, "hasMore": true }, "items": [ { "subjectId": "3325889774849773352", "subjectType": 2, "title": "Naruto", "detailPath": "naruto-2D7JgAQBGX3", "cover": "https://pbcdnw.aoneroom.com/image/.../naruto.jpg?x-oss-process=image/resize,w_360", "genre": "Anime,Action,Adventure", "releaseDate": "2005-09-10", "rating": "8.4", "country": "Japan" } ] } } ``` ## Browse GET https://api.animedoc.cloud/api/v2/anime/browse/ Docs: https://animedoc.cloud/docs/endpoints/browse List a channel (movies, series or animation) sorted by latest, most popular or top rated, optionally by genre and country. The building block for catalog pages and "latest" rows. channelId: 1 = movies, 2 = series, 1006 = animation. sort: Latest, Hottest or Rating. genre narrows it, e.g. Anime. Examples: newest anime channelId=2&genre=Anime&sort=Latest; anime movies channelId=1&genre=Anime; most popular movies channelId=1&sort=Hottest; top rated anime channelId=2&genre=Anime&sort=Rating; Bollywood channelId=1&country=India; Nollywood channelId=1&country=Nigeria; K-drama channelId=2&country=Korea. Parameters: - channelId (query, integer, default 2): 1 = movies, 2 = series, 1006 = animation. - sort (query, string, default Latest): Latest, Hottest or Rating. - genre (query, string): Optional genre filter, e.g. Anime, Action, Comedy, Horror. - country (query, string): Optional country filter: India (Bollywood), Nigeria (Nollywood), United States (Hollywood), Korea (K-drama)... - page (query, integer, default 1): Page number, starting at 1. - perPage (query, integer, default 24): Items per page (max 48). Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/browse/?channelId=2&sort=Latest&genre=Anime&page=1&perPage=24" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const params = new URLSearchParams({"channelId":"2","sort":"Latest","genre":"Anime","page":"1","perPage":"24"}); const res = await fetch("https://api.animedoc.cloud/api/v2/anime/browse/?" + params, { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/browse/", params={"channelId":2,"sort":"Latest","genre":"Anime","page":1,"perPage":24}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "pager": { "page": 1, "hasMore": true }, "items": [ { "subjectId": "3325889774849773352", "subjectType": 2, "title": "Naruto", "detailPath": "naruto-2D7JgAQBGX3", "cover": "https://pbcdnw.aoneroom.com/image/.../naruto.jpg?x-oss-process=image/resize,w_360", "genre": "Anime,Action,Adventure", "releaseDate": "2005-09-10", "rating": "8.4", "country": "Japan" } ] } } ``` ## Search Suggestions POST https://api.animedoc.cloud/api/v2/anime/suggest/ Docs: https://animedoc.cloud/docs/endpoints/search-suggestions Autocomplete: turn a partial keyword into likely search terms. Use it behind a search box: send what the user has typed so far and show the returned words as suggestions. It's cheap and fast, but each call still counts as one request, so debounce keystrokes (300 ms works well). Parameters: - keyword (body, string, required): The partial text the user typed. - perPage (body, integer, default 30): Maximum number of suggestions. Example (curl): ```bash curl -X POST "https://api.animedoc.cloud/api/v2/anime/suggest/" \ -H "X-API-Key: $ANIMEDOC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"keyword":"naru","perPage":5}' ``` Example (JavaScript): ```js const res = await fetch("https://api.animedoc.cloud/api/v2/anime/suggest/", { method: "POST", headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({"keyword":"naru","perPage":5}), }); if (res.status === 429) { console.log("Rate limited, retry in", res.headers.get("Retry-After"), "s"); } const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.post( "https://api.animedoc.cloud/api/v2/anime/suggest/", headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, json={"keyword":"naru","perPage":5}, timeout=15, ) if res.status_code == 429: print("Rate limited, retry in", res.headers["Retry-After"], "s") res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "items": [ { "word": "naruto" }, { "word": "naruto shippuden" }, { "word": "boruto naruto next generations" } ] } } ``` ## Search POST https://api.animedoc.cloud/api/v2/anime/search/ Docs: https://animedoc.cloud/docs/endpoints/search Full-text catalog search across anime, animation, movies and series, with pagination. Returns matching titles with cover art, genre, release date and rating. Each item has a subjectId and a detailPath: pass detailPath to Details, and both to Media Sources. One catalog covers anime and general movies; use subjectType to bias results and the genre field to split anime from everything else. Parameters: - keyword (body, string, required): What to search for. - page (body, integer, default 1): Page number, starting at 1. - perPage (body, integer, default 15): Results per page. - subjectType (body, integer, default 0): 0 = everything, 1 = movies, 2 = series. Example (curl): ```bash curl -X POST "https://api.animedoc.cloud/api/v2/anime/search/" \ -H "X-API-Key: $ANIMEDOC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"keyword":"naruto","page":1,"perPage":15,"subjectType":0}' ``` Example (JavaScript): ```js const res = await fetch("https://api.animedoc.cloud/api/v2/anime/search/", { method: "POST", headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({"keyword":"naruto","page":1,"perPage":15,"subjectType":0}), }); if (res.status === 429) { console.log("Rate limited, retry in", res.headers.get("Retry-After"), "s"); } const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.post( "https://api.animedoc.cloud/api/v2/anime/search/", headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, json={"keyword":"naruto","page":1,"perPage":15,"subjectType":0}, timeout=15, ) if res.status_code == 429: print("Rate limited, retry in", res.headers["Retry-After"], "s") res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "pager": { "hasMore": true, "totalCount": 48 }, "items": [ { "subjectId": "3325889774849773352", "subjectType": 2, "title": "Naruto", "description": "Naruto Uzumaki, a young ninja, seeks recognition...", "releaseDate": "2002-10-03", "genre": "Animation,Action,Adventure", "cover": { "url": "https://.../naruto.jpg" }, "countryName": "Japan", "imdbRatingValue": "8.4", "subtitles": "English,Spanish", "hasResource": true, "detailPath": "naruto-2D7JgAQBGX3" } ] } } ``` ## Details GET https://api.animedoc.cloud/api/v2/anime/detail/ Docs: https://animedoc.cloud/docs/endpoints/details Full metadata for one title, plus its seasons and episode counts. Look up a title by the detailPath from a search result. resource.seasons lists each season (se) and how many episodes it has (maxEp). A movie shows up as a single season with se: 0 and maxEp: 0. Parameters: - detailPath (query, string, required): The detailPath from a search result. Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/detail/?detailPath=naruto-2D7JgAQBGX3" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const params = new URLSearchParams({"detailPath":"naruto-2D7JgAQBGX3"}); const res = await fetch("https://api.animedoc.cloud/api/v2/anime/detail/?" + params, { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/detail/", params={"detailPath":"naruto-2D7JgAQBGX3"}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "subject": { "subjectId": "3325889774849773352", "subjectType": 2, "title": "Naruto", "description": "Naruto Uzumaki, a young ninja, seeks recognition...", "releaseDate": "2002-10-03", "genre": "Animation,Action,Adventure", "cover": { "url": "https://.../naruto.jpg" }, "countryName": "Japan", "imdbRatingValue": "8.4", "detailPath": "naruto-2D7JgAQBGX3", "dubs": [{ "lanName": "English", "lanCode": "en", "original": false, "detailPath": "naruto-english-..." }] }, "stars": [{ "name": "Junko Takeuchi", "character": "Naruto Uzumaki" }], "resource": { "seasons": [{ "se": 1, "maxEp": 220 }] } } } ``` ## Media Sources GET https://api.animedoc.cloud/api/v2/anime/media-sources/ Docs: https://animedoc.cloud/docs/endpoints/media-sources Playable video URLs (several resolutions) and subtitle tracks for one episode or movie. Resolves an episode to direct video files and captions. URLs are signed and expire, so request them right before playback and don't cache them. Skip entries with vipLocked: true or an empty url. For a movie, pass se=0&ep=0. CDN URLs usually refuse hotlinking from browsers, so play them through the Stream Proxy. Parameters: - subjectId (query, string, required): subjectId from Search or Details. - detailPath (query, string, required): detailPath from Search or Details. - se (query, integer, default 1): Season number (0 for movies). - ep (query, integer, default 1): Episode number (0 for movies). Example (curl): ```bash curl "https://api.animedoc.cloud/api/v2/anime/media-sources/?subjectId=3325889774849773352&detailPath=naruto-2D7JgAQBGX3&se=1&ep=1" \ -H "X-API-Key: $ANIMEDOC_API_KEY" ``` Example (JavaScript): ```js const params = new URLSearchParams({"subjectId":"3325889774849773352","detailPath":"naruto-2D7JgAQBGX3","se":"1","ep":"1"}); const res = await fetch("https://api.animedoc.cloud/api/v2/anime/media-sources/?" + params, { headers: { "X-API-Key": process.env.ANIMEDOC_API_KEY }, }); const { data } = await res.json(); console.log(data); ``` Example (Python): ```python import os import requests res = requests.get( "https://api.animedoc.cloud/api/v2/anime/media-sources/", params={"subjectId":"3325889774849773352","detailPath":"naruto-2D7JgAQBGX3","se":1,"ep":1}, headers={"X-API-Key": os.environ["ANIMEDOC_API_KEY"]}, timeout=15, ) res.raise_for_status() print(res.json()["data"]) ``` Example response: ``` { "code": 0, "message": "ok", "data": { "downloads": [ { "id": "1", "url": "https://cdn.../720.mp4?sign=...", "resolution": 720, "size": 145200000, "duration": 1380, "codecName": "h264", "vipLocked": false }, { "id": "2", "url": "https://cdn.../480.mp4?sign=...", "resolution": 480, "size": 81000000, "duration": 1380, "codecName": "h264", "vipLocked": false } ], "captions": [ { "id": "c1", "lan": "en", "lanName": "English", "url": "https://cdn.../en.srt" } ] } } ``` ## Stream Proxy GET https://api.animedoc.cloud/api/v2/anime/stream-file/ Docs: https://animedoc.cloud/docs/endpoints/stream-proxy Streams a Media Sources URL back through AnimeDoc, with byte-range support, so players can seek. Pass a url from Media Sources as video_url. The response is the video itself (video/mp4) with Accept-Ranges: bytes, so