- 
- 
+ 
+ 
A complete RESTful API for anime streaming data powered by AniList GraphQL and Miruro providers
Search, browse, filter, watch โ every endpoint returns fresh data with smart caching.
- 18 endpoints, 12 streaming providers, M3U8 URLs with subtitles and skip timestamps.
+ 35 endpoints, 12 streaming providers, M3U8 URLs with subtitles, skip timestamps, and batch operations.
@@ -84,7 +84,7 @@ ### Why MiruroAPI? -- ๐ฌ **18 Endpoints** โ Complete anime data coverage +- ๐ฌ **35 Endpoints** โ Complete anime data coverage - ๐ **Full-Text Search** โ Search anime by keyword with suggestions - ๐ญ **Characters & Voice Actors** โ Full character data from AniList - ๐ฏ **Advanced Filtering** โ Genre, year, season, format, sort @@ -92,6 +92,8 @@ - ๐ **Airing Schedule** โ See what's airing on any date - ๐ก **12 Streaming Providers** โ M3U8 streaming sources - โญ๏ธ **Skip Timestamps** โ OP/ED skip data +- ๐ญ **Character & Staff Search** โ Search characters and staff by name +- ๐ฌ **Batch Episodes** โ Fetch multiple episode sources in parallel - โก **Smart Caching** โ In-memory Map with configurable TTL - ๐ **CORS Enabled** โ Works from any frontend, no proxy needed - ๐ **Zero-Config Deploy** โ One click to Vercel, or run standalone with Express @@ -138,7 +140,9 @@ flowchart TD - **AniList GraphQL** for rich metadata - **Miruro pipe** for streaming sources - **Smart caching** with configurable TTL -- **18 RESTful endpoints** +- **35 RESTful endpoints** +- **Gzip compression** โ 30-70% smaller responses +- **Request logging** โ method, path, status, duration - **Graceful error handling** per endpoint - **Rate limiting** (100 req/min per IP) @@ -152,6 +156,9 @@ flowchart TD - **Characters** with voice actors - **Relations** and **Recommendations** - **Airing schedule** by date +- **Seasonal anime** by year + season +- **Studio filter** โ anime by studio name +- **Character & Staff search** @@ -165,6 +172,9 @@ flowchart TD - **Download links** when available - **Sub/Dub** support per provider - **Codec and fansub** metadata +- **Batch episode fetching** โ multiple sources in parallel +- **Quality fallback** โ auto 1080p โ 720p โ 360p +- **Subtitle extraction** โ expose subtitle URLs
npm start to run the Express server on any VPS, Docker con
### โ
Completed
-- [x] ๐ฌ 18 API endpoints covering all data
+- [x] ๐ฌ 35 API endpoints covering all data
- [x] ๐ Full-text search with pagination
- [x] ๐ก Search suggestions for autocomplete
- [x] ๐ฏ Advanced filtering (genre, year, season, format, sort)
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 536a3cd..a14e6aa 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -1,29 +1,553 @@
# API Endpoints Reference
-Complete documentation for all 18 MiruroAPI endpoints.
+Complete documentation for all 35 MiruroAPI v2.0.0 endpoints.
---
## Table of Contents
-- [Health Check](#health-check)
-- [Stats](#stats)
+### Search & Discovery
- [Search](#search)
- [Suggestions](#suggestions)
- [Filter](#filter)
+- [Multi-Search](#multi-search)
+
+### Collections
- [Trending](#trending)
+- [Trending Daily](#trending-daily)
+- [Trending Weekly](#trending-weekly)
- [Popular](#popular)
+- [Top](#top)
- [Upcoming](#upcoming)
- [Recent](#recent)
- [Spotlight](#spotlight)
- [Schedule](#schedule)
+- [Random](#random)
+- [Upcoming Countdown](#upcoming-countdown)
+
+### Seasonal & Studio
+- [Seasonal Anime](#seasonal-anime)
+- [Anime by Studio](#anime-by-studio)
+
+### Genres & Tags
+- [Genres](#genres)
+- [Tags](#tags)
+- [Anime by Genre](#anime-by-genre)
+- [Anime by Year](#anime-by-year)
+- [Anime by Status](#anime-by-status)
+- [Anime by Format](#anime-by-format)
+
+### Character & Staff
+- [Character Detail](#character-detail)
+- [Staff Detail](#staff-detail)
+- [Search Characters](#search-characters)
+- [Search Staff](#search-staff)
+
+### Anime Details
- [Anime Info](#anime-info)
- [Characters](#characters)
- [Relations](#relations)
- [Recommendations](#recommendations)
+
+### Streaming & Downloading
- [Episodes](#episodes)
+- [Batch Episodes](#batch-episodes)
+- [Sources (Detailed)](#sources-detailed)
+- [Stream (Quality Fallback)](#stream-quality-fallback)
+- [Download URL](#download-url)
- [Watch (Streaming)](#watch-streaming)
+### Utility
+- [Compare](#compare)
+- [Genre Stats](#genre-stats)
+- [Calendar](#calendar)
+- [Timeline](#timeline)
+
+### System
+- [Health Check](#health-check)
+- [Stats](#stats)
+- [OpenAPI](#openapi)
+
+---
+
+## Search
+
+```
+GET /api/search?query=naruto
+```
+
+Full-text anime search with pagination.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| query | string | required | Search query |
+| page | int | 1 | Page number |
+| per_page | int | 20 | Results per page (max 50) |
+
+---
+
+## Suggestions
+
+```
+GET /api/suggestions?query=naruto
+```
+
+Lightweight autocomplete suggestions (max 8 results).
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| query | string | required | Search query |
+
+---
+
+## Filter
+
+```
+GET /api/filter?genre=Action&year=2024&season=SPRING
+```
+
+Advanced anime filter with multiple parameters.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| genre | string | โ | Genre name |
+| tag | string | โ | Tag name |
+| year | int | โ | Season year |
+| season | string | โ | WINTER, SPRING, SUMMER, FALL |
+| format | string | โ | TV, MOVIE, OVA, ONA, SPECIAL |
+| status | string | โ | RELEASING, FINISHED, NOT_YET_RELEASED |
+| sort | string | POPULARITY_DESC | Sort order |
+| page | int | 1 | Page number |
+| per_page | int | 20 | Results per page |
+
+---
+
+## Multi-Search
+
+```
+GET /api/multi-search?q=naruto&genre=Action&year=2024
+```
+
+Combined query + filters search.
+
+---
+
+## Trending
+
+```
+GET /api/trending?page=1&per_page=20
+```
+
+Currently trending anime.
+
+---
+
+## Trending Daily
+
+```
+GET /api/trending/daily
+```
+
+Trending anime from the last 7 days.
+
+---
+
+## Trending Weekly
+
+```
+GET /api/trending/weekly
+```
+
+Trending anime from the last 30 days.
+
+---
+
+## Popular
+
+```
+GET /api/popular
+```
+
+Most popular anime of all time.
+
+---
+
+## Top
+
+```
+GET /api/top
+```
+
+Top anime by score (all time).
+
+---
+
+## Upcoming
+
+```
+GET /api/upcoming
+```
+
+Most anticipated upcoming anime.
+
+---
+
+## Recent
+
+```
+GET /api/recent
+```
+
+Currently airing anime.
+
+---
+
+## Spotlight
+
+```
+GET /api/spotlight
+```
+
+Top 10 trending + popular anime for hero banners.
+
+---
+
+## Schedule
+
+```
+GET /api/schedule?page=1&per_page=20
+```
+
+Airing schedule with timestamps.
+
+---
+
+## Random
+
+```
+GET /api/random
+```
+
+Returns a random anime.
+
+---
+
+## Upcoming Countdown
+
+```
+GET /api/upcoming/countdown
+```
+
+Next 10 episodes airing soon.
+
+---
+
+## Seasonal Anime
+
+```
+GET /api/season/2025/spring
+```
+
+Anime for a specific year and season.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| year | int | required | Year (e.g., 2025) |
+| season | string | required | WINTER, SPRING, SUMMER, FALL |
+
+---
+
+## Anime by Studio
+
+```
+GET /api/studio/MAPPA
+```
+
+All anime produced by a specific studio.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| name | string | required | Studio name |
+
+---
+
+## Genres
+
+```
+GET /api/genres
+```
+
+Returns all available genres from AniList.
+
+---
+
+## Tags
+
+```
+GET /api/tags
+```
+
+Returns all available tags from AniList.
+
+---
+
+## Anime by Genre
+
+```
+GET /api/genre/Action
+```
+
+All anime in a specific genre.
+
+---
+
+## Anime by Year
+
+```
+GET /api/year/2024
+```
+
+All anime from a specific year.
+
+---
+
+## Anime by Status
+
+```
+GET /api/status/RELEASING
+```
+
+All anime with a specific status (RELEASING, FINISHED, NOT_YET_RELEASED).
+
+---
+
+## Anime by Format
+
+```
+GET /api/format/MOVIE
+```
+
+All anime with a specific format (TV, MOVIE, OVA, ONA, SPECIAL).
+
+---
+
+## Character Detail
+
+```
+GET /api/character/1
+```
+
+Detailed character info with anime list.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| id | int | required | AniList character ID |
+
+---
+
+## Staff Detail
+
+```
+GET /api/staff/1
+```
+
+Detailed staff info with anime list.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| id | int | required | AniList staff ID |
+
+---
+
+## Search Characters
+
+```
+GET /api/characters?query=kaneki
+```
+
+Search characters by name.
+
+---
+
+## Search Staff
+
+```
+GET /api/staff?query=oda
+```
+
+Search staff by name.
+
+---
+
+## Anime Info
+
+```
+GET /api/info/20605
+```
+
+Complete anime info including characters, relations, recommendations, trailer, stats.
+
+---
+
+## Characters
+
+```
+GET /api/anime/20605/characters?page=1&per_page=25
+```
+
+Paginated character list with voice actors.
+
+---
+
+## Relations
+
+```
+GET /api/anime/20605/relations
+```
+
+Related anime (sequels, prequels, spin-offs).
+
+---
+
+## Recommendations
+
+```
+GET /api/anime/20605/recommendations?page=1&per_page=10
+```
+
+Community recommendations sorted by rating.
+
+---
+
+## Episodes
+
+```
+GET /api/episodes/20605
+```
+
+Episode list from all providers with sub/dub support.
+
+---
+
+## Batch Episodes
+
+```
+GET /api/episodes/20605/batch?provider=kiwi&category=sub&slugs=animepahe-1,animepahe-2
+```
+
+Fetch multiple episode sources in parallel.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| provider | string | kiwi | Provider name |
+| category | string | sub | sub or dub |
+| slugs | string | required | Comma-separated episode slugs |
+
+---
+
+## Sources (Detailed)
+
+```
+GET /api/sources?episodeId=xxx&provider=kiwi&anilistId=20605&category=sub
+```
+
+Streaming sources with raw episode ID.
+
+---
+
+## Stream (Quality Fallback)
+
+```
+GET /api/stream?provider=kiwi&anilistId=20605&category=sub&slug=animepahe-1&quality=1080p
+```
+
+Streaming sources with automatic quality fallback.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| provider | string | required | Provider name |
+| anilistId | int | required | AniList anime ID |
+| category | string | sub | sub or dub |
+| slug | string | required | Episode slug |
+| quality | string | 1080p | Preferred quality |
+
+---
+
+## Download URL
+
+```
+GET /api/download?provider=kiwi&anilistId=20605&category=sub&slug=animepahe-1
+```
+
+Returns the download URL for an episode.
+
+---
+
+## Watch (Streaming)
+
+```
+GET /api/watch/kiwi/20605/sub/animepahe-1
+```
+
+Streaming sources via URL path (recommended).
+
+| Param | Type | Description |
+|-------|------|-------------|
+| provider | string | Provider name |
+| anilistId | int | AniList anime ID |
+| category | string | sub or dub |
+| slug | string | Episode slug |
+
+---
+
+## Compare
+
+```
+GET /api/compare/20605/20
+```
+
+Compare two anime side by side.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| id1 | int | First anime ID |
+| id2 | int | Second anime ID |
+
+---
+
+## Genre Stats
+
+```
+GET /api/stats/genre
+```
+
+Genre statistics with top anime per genre.
+
+---
+
+## Calendar
+
+```
+GET /api/calendar?year=2025&month=6
+```
+
+Monthly airing calendar.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| year | int | current | Year |
+| month | int | current | Month (1-12) |
+
+---
+
+## Timeline
+
+```
+GET /api/timeline/20605
+```
+
+Anime release timeline with prequels, sequels, spin-offs.
+
---
## Health Check
@@ -32,7 +556,7 @@ Complete documentation for all 18 MiruroAPI endpoints.
GET /api/health
```
-Returns API health status, version, uptime, memory usage, and available providers.
+API health status, version, uptime, memory, cache stats.
**Response:**
@@ -41,11 +565,12 @@ Returns API health status, version, uptime, memory usage, and available provider
"success": true,
"results": {
"status": "healthy",
- "version": "1.2.0",
+ "version": "2.0.0",
"uptime": "0h 0m 34s",
"node": "v24.14.1",
- "memory": { "used": "13MB", "total": "15MB" },
- "endpoints": 16,
+ "memory": { "used": "13MB", "total": "15MB", "rss": "25MB" },
+ "cache": { "size": 12, "maxSize": 100 },
+ "endpoints": 35,
"providers": ["kiwi","pewe","bee","bonk","bun","ally","nun","twin","cog","moo","hop","telli"]
}
}
@@ -59,317 +584,20 @@ Returns API health status, version, uptime, memory usage, and available provider
GET /api/stats
```
-Returns request statistics, cache info, and memory usage.
+Cache & API statistics including request count and success rate.
---
-## Search
+## OpenAPI
```
-GET /api/search
+GET /api/openapi
```
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `query` | string | Yes | โ | Search keyword |
-| `page` | number | No | 1 | Page number |
-| `per_page` | number | No | 20 | Results per page |
-
-**Example:** `GET /api/search?query=naruto&per_page=2`
-
-**Response:**
-
-```json
-{
- "success": true,
- "results": {
- "page": 1,
- "perPage": 2,
- "total": 5000,
- "hasNextPage": true,
- "results": [
- {
- "id": 20,
- "title": { "romaji": "NARUTO", "english": "Naruto", "native": "NARUTO -ใใซใ-" },
- "coverImage": { "large": "https://s4.anilist.co/file/..." },
- "format": "TV",
- "episodes": 220,
- "status": "FINISHED",
- "averageScore": 80,
- "genres": ["Action","Adventure","Comedy","Drama","Fantasy","Supernatural"]
- }
- ]
- }
-}
-```
+Returns the OpenAPI 3.0.3 specification in JSON format.
---
-## Suggestions
-
-```
-GET /api/suggestions
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `query` | string | Yes | Search keyword |
-
-**Example:** `GET /api/suggestions?query=naruto`
-
-Returns fast autocomplete suggestions with title, poster, format, status, year, and episode count.
-
----
-
-## Filter
-
-```
-GET /api/filter
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `genre` | string | No | โ | Genre name (e.g. "Action") |
-| `tag` | string | No | โ | Tag name |
-| `year` | number | No | โ | Release year |
-| `season` | string | No | โ | FALL, WINTER, SPRING, SUMMER |
-| `format` | string | No | โ | TV, MOVIE, OVA, ONA, SPECIAL, MUSIC |
-| `status` | string | No | โ | RELEASING, FINISHED, NOT_YET_RELEASED, CANCELLED |
-| `sort` | string | No | POPULARITY_DESC | Sort order |
-| `page` | number | No | 1 | Page number |
-| `per_page` | number | No | 20 | Results per page |
-
-**Example:** `GET /api/filter?genre=Action&year=2024&season=WINTER&per_page=3`
-
----
-
-## Trending
-
-```
-GET /api/trending
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `per_page` | number | No | 20 | Results per page |
-
-**Example:** `GET /api/trending?per_page=5`
-
----
-
-## Popular
-
-```
-GET /api/popular
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `per_page` | number | No | 20 | Results per page |
-
----
-
-## Upcoming
-
-```
-GET /api/upcoming
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `per_page` | number | No | 20 | Results per page |
-
----
-
-## Recent
-
-```
-GET /api/recent
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `per_page` | number | No | 20 | Results per page |
-
----
-
-## Spotlight
-
-```
-GET /api/spotlight
-```
-
-Returns featured/spotlight anime for the hero carousel.
-
----
-
-## Schedule
-
-```
-GET /api/schedule
-```
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `date` | string | No | today | Date in YYYY-MM-DD format |
-
----
-
-## Anime Info
-
-```
-GET /api/info/:id
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | number | Yes | AniList anime ID |
-
-**Example:** `GET /api/info/20`
-
-**Response:**
-
-```json
-{
- "success": true,
- "results": {
- "id": 20,
- "idMal": 20,
- "title": { "romaji": "NARUTO", "english": "Naruto", "native": "NARUTO -ใใซใ-" },
- "description": "Naruto Uzumaki, a hyperactive and knuckle-headed ninja...",
- "coverImage": { "large": "https://s4.anilist.co/file/..." },
- "format": "TV",
- "episodes": 220,
- "duration": 23,
- "status": "FINISHED",
- "averageScore": 80,
- "genres": ["Action","Adventure","Comedy","Drama","Fantasy","Supernatural"],
- "studios": [{ "name": "Studio Pierrot", "isAnimationStudio": true }]
- }
-}
-```
-
----
-
-## Characters
-
-```
-GET /api/anime/:id/characters
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | number | Yes | AniList anime ID |
-
-**Example:** `GET /api/anime/20/characters`
-
-Returns characters with voice actors.
-
----
-
-## Relations
-
-```
-GET /api/anime/:id/relations
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | number | Yes | AniList anime ID |
-
-Returns related anime (sequels, prequels, side stories, etc.).
-
----
-
-## Recommendations
-
-```
-GET /api/anime/:id/recommendations
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | number | Yes | AniList anime ID |
-
-Returns recommended anime based on the given ID.
-
----
-
-## Episodes
-
-```
-GET /api/episodes/:id
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | number | Yes | AniList anime ID |
-
-**Example:** `GET /api/episodes/20`
-
-**Response:**
-
-```json
-{
- "success": true,
- "results": {
- "providers": {
- "kiwi": {
- "meta": { "id": "1571", "title": "Naruto", "type": "TV" },
- "episodes": {
- "sub": [
- {
- "id": "watch/kiwi/20/sub/animepahe-1",
- "number": 1,
- "title": "Enter: Naruto Uzumaki!",
- "airDate": "2002-10-03",
- "audio": "sub",
- "filler": false
- }
- ]
- }
- }
- }
- }
-}
-```
-
----
-
-## Watch (Streaming)
-
-```
-GET /api/watch/:provider/:anilistId/:category/:slug
-```
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | Provider name (kiwi, pewe, etc.) |
-| `anilistId` | number | Yes | AniList anime ID |
-| `category` | string | Yes | sub or dub |
-| `slug` | string | Yes | Episode slug from episodes response |
-
-**Example:** `GET /api/watch/kiwi/20/sub/animepahe-1`
-
-**Response:**
-
-```json
-{
- "success": true,
- "results": {
- "streams": [
- {
- "url": "https://vault-01.uwucdn.top/stream/.../uwu.m3u8",
- "type": "hls",
- "quality": "360p",
- "resolution": { "width": 640, "height": 360 },
- "codec": "h264",
- "audio": "sub",
- "fansub": "df68",
- "referer": "https://kwik.cx/e/..."
- }
- ],
- "download": "https://pahe.win/LJmbA"
- }
-}
-```
+> ๐ All endpoints return `{ "success": true, "results": {...} }` on success and `{ "success": false, "message": "..." }` on error.
+>
+> ๐ฌ Creator attribution is injected into every response: `{ "creator": "Shinei Nouzen", "github": "...", "telegram": "...", "message": "...", "timestamp": "..." }`
diff --git a/public/openapi.json b/public/openapi.json
index 5643cb9..b39a75c 100644
--- a/public/openapi.json
+++ b/public/openapi.json
@@ -3,7 +3,7 @@
"info": {
"title": "MiruroAPI",
"description": "Free RESTful API for anime streaming data. Powered by AniList GraphQL and Miruro streaming providers.",
- "version": "1.1.0",
+ "version": "2.0.0",
"contact": {
"name": "Shineii86",
"url": "https://github.com/Shineii86/MiruroAPI"
@@ -18,230 +18,388 @@
"description": "Production"
}
],
+ "tags": [
+ { "name": "Search", "description": "Search, filter, suggestions" },
+ { "name": "Collections", "description": "Trending, popular, top, schedule" },
+ { "name": "Seasonal & Studio", "description": "Seasonal anime, studio filter" },
+ { "name": "Genres & Tags", "description": "Genre, year, status, format filters" },
+ { "name": "Character & Staff", "description": "Character/staff details and search" },
+ { "name": "Anime Details", "description": "Info, characters, relations, recommendations" },
+ { "name": "Streaming", "description": "Episodes, sources, stream, download" },
+ { "name": "Utility", "description": "Compare, stats, calendar, timeline" },
+ { "name": "System", "description": "Health, stats, OpenAPI" }
+ ],
"paths": {
- "/api/health": {
- "get": {
- "tags": ["System"],
- "summary": "Health check",
- "operationId": "health",
- "responses": {
- "200": {
- "description": "API is healthy",
- "content": { "application/json": { "schema": { "type": "object" } } }
- }
- }
- }
- },
"/api/search": {
"get": {
- "tags": ["Search & Discovery"],
+ "tags": ["Search"],
"summary": "Search anime by name",
- "operationId": "searchAnime",
"parameters": [
- { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" },
+ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } },
{ "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
{ "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
- ],
- "responses": {
- "200": { "description": "Search results with pagination" }
- }
+ ]
}
},
"/api/suggestions": {
"get": {
- "tags": ["Search & Discovery"],
+ "tags": ["Search"],
"summary": "Autocomplete suggestions",
- "operationId": "getSuggestions",
"parameters": [
{ "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }
- ],
- "responses": {
- "200": { "description": "Lightweight suggestions (max 8)" }
- }
+ ]
}
},
"/api/filter": {
"get": {
- "tags": ["Search & Discovery"],
- "summary": "Advanced filter / browse",
- "operationId": "filterAnime",
+ "tags": ["Search"],
+ "summary": "Advanced filter",
"parameters": [
- { "name": "genre", "in": "query", "schema": { "type": "string" }, "description": "e.g. Action, Romance" },
- { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "e.g. Isekai, Time Skip" },
+ { "name": "genre", "in": "query", "schema": { "type": "string" } },
+ { "name": "tag", "in": "query", "schema": { "type": "string" } },
{ "name": "year", "in": "query", "schema": { "type": "integer" } },
{ "name": "season", "in": "query", "schema": { "type": "string", "enum": ["WINTER", "SPRING", "SUMMER", "FALL"] } },
- { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["TV", "MOVIE", "OVA", "ONA", "SPECIAL", "MUSIC"] } },
- { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["RELEASING", "FINISHED", "NOT_YET_RELEASED", "CANCELLED", "HIATUS"] } },
- { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["SCORE_DESC", "POPULARITY_DESC", "TRENDING_DESC", "START_DATE_DESC", "FAVOURITES_DESC", "UPDATED_AT_DESC"], "default": "POPULARITY_DESC" } },
+ { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["TV", "MOVIE", "OVA", "ONA", "SPECIAL"] } },
+ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["RELEASING", "FINISHED", "NOT_YET_RELEASED"] } },
+ { "name": "sort", "in": "query", "schema": { "type": "string", "default": "POPULARITY_DESC" } },
{ "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
- ],
- "responses": {
- "200": { "description": "Filtered results with pagination" }
- }
+ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
+ ]
+ }
+ },
+ "/api/multi-search": {
+ "get": {
+ "tags": ["Search"],
+ "summary": "Multi-parameter search"
}
},
"/api/trending": {
"get": {
"tags": ["Collections"],
- "summary": "Trending anime",
- "operationId": "getTrending",
- "parameters": [
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
- ],
- "responses": { "200": { "description": "Trending anime list" } }
+ "summary": "Trending anime"
+ }
+ },
+ "/api/trending/daily": {
+ "get": {
+ "tags": ["Collections"],
+ "summary": "Daily trending anime"
+ }
+ },
+ "/api/trending/weekly": {
+ "get": {
+ "tags": ["Collections"],
+ "summary": "Weekly trending anime"
}
},
"/api/popular": {
"get": {
"tags": ["Collections"],
- "summary": "Most popular anime",
- "operationId": "getPopular",
- "parameters": [
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
- ],
- "responses": { "200": { "description": "Popular anime list" } }
+ "summary": "Most popular anime"
+ }
+ },
+ "/api/top": {
+ "get": {
+ "tags": ["Collections"],
+ "summary": "Top anime by score"
}
},
"/api/upcoming": {
"get": {
"tags": ["Collections"],
- "summary": "Upcoming anime",
- "operationId": "getUpcoming",
- "parameters": [
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
- ],
- "responses": { "200": { "description": "Upcoming anime list" } }
+ "summary": "Upcoming anime"
}
},
"/api/recent": {
"get": {
"tags": ["Collections"],
- "summary": "Recently updated anime",
- "operationId": "getRecent",
- "parameters": [
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
- ],
- "responses": { "200": { "description": "Recent anime list" } }
+ "summary": "Recently aired anime"
}
},
"/api/spotlight": {
"get": {
"tags": ["Collections"],
- "summary": "Spotlight / featured anime",
- "operationId": "getSpotlight",
- "responses": { "200": { "description": "Top 10 trending + popular" } }
+ "summary": "Spotlight/featured anime"
}
},
"/api/schedule": {
"get": {
"tags": ["Collections"],
- "summary": "Airing schedule",
- "operationId": "getSchedule",
+ "summary": "Airing schedule"
+ }
+ },
+ "/api/random": {
+ "get": {
+ "tags": ["Collections"],
+ "summary": "Random anime"
+ }
+ },
+ "/api/upcoming/countdown": {
+ "get": {
+ "tags": ["Collections"],
+ "summary": "Next 10 episodes airing soon"
+ }
+ },
+ "/api/season/{year}/{season}": {
+ "get": {
+ "tags": ["Seasonal & Studio"],
+ "summary": "Seasonal anime",
"parameters": [
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
- ],
- "responses": { "200": { "description": "Upcoming episodes with timestamps" } }
+ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer" } },
+ { "name": "season", "in": "path", "required": true, "schema": { "type": "string", "enum": ["WINTER", "SPRING", "SUMMER", "FALL"] } }
+ ]
+ }
+ },
+ "/api/studio/{name}": {
+ "get": {
+ "tags": ["Seasonal & Studio"],
+ "summary": "Anime by studio",
+ "parameters": [
+ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }
+ ]
+ }
+ },
+ "/api/genres": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "All genres"
+ }
+ },
+ "/api/tags": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "All tags"
+ }
+ },
+ "/api/genre/{name}": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "Anime by genre",
+ "parameters": [
+ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }
+ ]
+ }
+ },
+ "/api/year/{year}": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "Anime by year",
+ "parameters": [
+ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/status/{status}": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "Anime by status",
+ "parameters": [
+ { "name": "status", "in": "path", "required": true, "schema": { "type": "string", "enum": ["RELEASING", "FINISHED", "NOT_YET_RELEASED"] } }
+ ]
+ }
+ },
+ "/api/format/{format}": {
+ "get": {
+ "tags": ["Genres & Tags"],
+ "summary": "Anime by format",
+ "parameters": [
+ { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": ["TV", "MOVIE", "OVA", "ONA", "SPECIAL"] } }
+ ]
+ }
+ },
+ "/api/character/{id}": {
+ "get": {
+ "tags": ["Character & Staff"],
+ "summary": "Character detail",
+ "parameters": [
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/staff/{id}": {
+ "get": {
+ "tags": ["Character & Staff"],
+ "summary": "Staff detail",
+ "parameters": [
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/characters": {
+ "get": {
+ "tags": ["Character & Staff"],
+ "summary": "Search characters",
+ "parameters": [
+ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }
+ ]
+ }
+ },
+ "/api/staff": {
+ "get": {
+ "tags": ["Character & Staff"],
+ "summary": "Search staff",
+ "parameters": [
+ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }
+ ]
}
},
"/api/info/{id}": {
"get": {
"tags": ["Anime Details"],
"summary": "Full anime info",
- "operationId": "getAnimeInfo",
"parameters": [
- { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "AniList anime ID" }
- ],
- "responses": { "200": { "description": "Complete anime metadata, characters, relations, recommendations" } }
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
}
},
"/api/anime/{id}/characters": {
"get": {
"tags": ["Anime Details"],
- "summary": "Characters with voice actors",
- "operationId": "getCharacters",
+ "summary": "Characters",
"parameters": [
- { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 25 } }
- ],
- "responses": { "200": { "description": "Paginated character list" } }
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
}
},
"/api/anime/{id}/relations": {
"get": {
"tags": ["Anime Details"],
- "summary": "Related anime",
- "operationId": "getRelations",
+ "summary": "Relations",
"parameters": [
{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
- ],
- "responses": { "200": { "description": "Sequels, prequels, side stories, etc." } }
+ ]
}
},
"/api/anime/{id}/recommendations": {
"get": {
"tags": ["Anime Details"],
- "summary": "Community recommendations",
- "operationId": "getRecommendations",
+ "summary": "Recommendations",
"parameters": [
- { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
- { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
- { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 10 } }
- ],
- "responses": { "200": { "description": "Recommended anime sorted by rating" } }
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
}
},
"/api/episodes/{id}": {
"get": {
"tags": ["Streaming"],
- "summary": "Episode list from all providers",
- "operationId": "getEpisodes",
+ "summary": "Episode list",
"parameters": [
- { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "AniList anime ID" }
- ],
- "responses": { "200": { "description": "Episodes organized by provider and audio type (sub/dub)" } }
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/episodes/{id}/batch": {
+ "get": {
+ "tags": ["Streaming"],
+ "summary": "Batch episode sources",
+ "parameters": [
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
+ { "name": "provider", "in": "query", "schema": { "type": "string", "default": "kiwi" } },
+ { "name": "category", "in": "query", "schema": { "type": "string", "default": "sub" } },
+ { "name": "slugs", "in": "query", "schema": { "type": "string" } }
+ ]
}
},
"/api/sources": {
"get": {
"tags": ["Streaming"],
"summary": "Streaming sources (detailed)",
- "operationId": "getSources",
"parameters": [
{ "name": "episodeId", "in": "query", "required": true, "schema": { "type": "string" } },
{ "name": "provider", "in": "query", "required": true, "schema": { "type": "string" } },
{ "name": "anilistId", "in": "query", "required": true, "schema": { "type": "integer" } },
- { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["sub", "dub"], "default": "sub" } }
- ],
- "responses": { "200": { "description": "M3U8 streams, subtitles, intro/outro timestamps" } }
+ { "name": "category", "in": "query", "schema": { "type": "string", "default": "sub" } }
+ ]
+ }
+ },
+ "/api/stream": {
+ "get": {
+ "tags": ["Streaming"],
+ "summary": "Stream with quality fallback",
+ "parameters": [
+ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" } },
+ { "name": "anilistId", "in": "query", "required": true, "schema": { "type": "integer" } },
+ { "name": "category", "in": "query", "schema": { "type": "string", "default": "sub" } },
+ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string" } },
+ { "name": "quality", "in": "query", "schema": { "type": "string", "default": "1080p" } }
+ ]
+ }
+ },
+ "/api/download": {
+ "get": {
+ "tags": ["Streaming"],
+ "summary": "Download URL",
+ "parameters": [
+ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" } },
+ { "name": "anilistId", "in": "query", "required": true, "schema": { "type": "integer" } },
+ { "name": "category", "in": "query", "schema": { "type": "string", "default": "sub" } },
+ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string" } }
+ ]
}
},
"/api/watch/{provider}/{anilistId}/{category}/{slug}": {
"get": {
"tags": ["Streaming"],
- "summary": "Streaming sources (simple slug-based)",
- "operationId": "getWatchSources",
+ "summary": "Streaming sources (simple)",
"parameters": [
{ "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "anilistId", "in": "path", "required": true, "schema": { "type": "integer" } },
- { "name": "category", "in": "path", "required": true, "schema": { "type": "string", "enum": ["sub", "dub"] } },
- { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "e.g. animepahe-1" }
- ],
- "responses": { "200": { "description": "M3U8 streams, subtitles, intro/outro timestamps" } }
+ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" } },
+ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
+ ]
+ }
+ },
+ "/api/compare/{id1}/{id2}": {
+ "get": {
+ "tags": ["Utility"],
+ "summary": "Compare two anime",
+ "parameters": [
+ { "name": "id1", "in": "path", "required": true, "schema": { "type": "integer" } },
+ { "name": "id2", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/stats/genre": {
+ "get": {
+ "tags": ["Utility"],
+ "summary": "Genre statistics"
+ }
+ },
+ "/api/calendar": {
+ "get": {
+ "tags": ["Utility"],
+ "summary": "Monthly airing calendar",
+ "parameters": [
+ { "name": "year", "in": "query", "schema": { "type": "integer" } },
+ { "name": "month", "in": "query", "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/timeline/{id}": {
+ "get": {
+ "tags": ["Utility"],
+ "summary": "Anime timeline",
+ "parameters": [
+ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+ ]
+ }
+ },
+ "/api/health": {
+ "get": {
+ "tags": ["System"],
+ "summary": "Health check"
+ }
+ },
+ "/api/stats": {
+ "get": {
+ "tags": ["System"],
+ "summary": "API statistics"
+ }
+ },
+ "/api/openapi": {
+ "get": {
+ "tags": ["System"],
+ "summary": "OpenAPI spec"
}
}
- },
- "tags": [
- { "name": "System", "description": "Health & status" },
- { "name": "Search & Discovery", "description": "Search, suggestions, and advanced filtering" },
- { "name": "Collections", "description": "Trending, popular, upcoming, recent, spotlight, schedule" },
- { "name": "Anime Details", "description": "Full anime info, characters, relations, recommendations" },
- { "name": "Streaming", "description": "Episode lists and M3U8 streaming sources" }
- ]
+ }
}
diff --git a/test.js b/test.js
index 686fb3d..a3824e3 100644
--- a/test.js
+++ b/test.js
@@ -4,8 +4,8 @@
* Repository: https://github.com/Shineii86/MiruroAPI
*
* @description
- * Integration test suite for MiruroAPI endpoints.
- * Tests all major endpoints for correct response format.
+ * Integration test suite for MiruroAPI v2.0.0 endpoints.
+ * Tests all 35 endpoints for correct response format.
*
* @author Shinei Nouzen
* @license MIT
@@ -15,24 +15,66 @@
const BASE = process.env.API_URL || "https://mirurotvapi.vercel.app/api";
const tests = [
+ // System
{ name: "Health", url: "/health" },
{ name: "Stats", url: "/stats" },
{ name: "OpenAPI", url: "/openapi" },
+
+ // Search & Discovery
{ name: "Search", url: "/search?query=naruto" },
{ name: "Suggestions", url: "/suggestions?query=naruto" },
{ name: "Filter", url: "/filter?genre=Action&per_page=1" },
+ { name: "Multi-Search", url: "/multi-search?q=naruto&genre=Action" },
+
+ // Collections
{ name: "Trending", url: "/trending?per_page=1" },
+ { name: "Trending Daily", url: "/trending/daily" },
+ { name: "Trending Weekly", url: "/trending/weekly" },
{ name: "Popular", url: "/popular?per_page=1" },
+ { name: "Top", url: "/top?per_page=1" },
{ name: "Upcoming", url: "/upcoming?per_page=1" },
{ name: "Recent", url: "/recent?per_page=1" },
{ name: "Spotlight", url: "/spotlight" },
{ name: "Schedule", url: "/schedule" },
+ { name: "Random", url: "/random" },
+ { name: "Upcoming Countdown", url: "/upcoming/countdown" },
+
+ // Seasonal & Studio
+ { name: "Seasonal", url: "/season/2025/spring" },
+ { name: "Studio", url: "/studio/MAPPA" },
+
+ // Genres & Tags
+ { name: "Genres", url: "/genres" },
+ { name: "Tags", url: "/tags" },
+ { name: "Genre", url: "/genre/Action" },
+ { name: "Year", url: "/year/2024" },
+ { name: "Status", url: "/status/RELEASING" },
+ { name: "Format", url: "/format/MOVIE" },
+
+ // Character & Staff
+ { name: "Character", url: "/character/1" },
+ { name: "Staff", url: "/staff/1" },
+ { name: "Characters Search", url: "/characters?query=kaneki" },
+ { name: "Staff Search", url: "/staff?query=oda" },
+
+ // Anime Details
{ name: "Info", url: "/info/20" },
- { name: "Characters", url: "/anime/20/characters" },
+ { name: "Anime Characters", url: "/anime/20/characters" },
{ name: "Relations", url: "/anime/20/relations" },
{ name: "Recommendations", url: "/anime/20/recommendations" },
+
+ // Streaming
{ name: "Episodes", url: "/episodes/20" },
+ { name: "Batch Episodes", url: "/episodes/20/batch?provider=kiwi&category=sub&slugs=animepahe-1,animepahe-2" },
+ { name: "Stream", url: "/stream?provider=kiwi&anilistId=20&category=sub&slug=animepahe-1" },
+ { name: "Download", url: "/download?provider=kiwi&anilistId=20&category=sub&slug=animepahe-1" },
{ name: "Watch", url: "/watch/kiwi/20/sub/animepahe-1" },
+
+ // Utility
+ { name: "Compare", url: "/compare/20/21" },
+ { name: "Genre Stats", url: "/stats/genre" },
+ { name: "Calendar", url: "/calendar" },
+ { name: "Timeline", url: "/timeline/20" },
];
let passed = 0;
@@ -61,7 +103,7 @@ async function runTest(test) {
}
async function runAll() {
- console.log(`\n๐งช Running ${tests.length} tests...\n`);
+ console.log(`\n๐งช MiruroAPI v2.0.0 โ Running ${tests.length} tests...\n`);
for (const test of tests) {
await runTest(test);