MiruroAPI/docs/endpoints.md

API Endpoints Reference

Complete documentation for all 18 MiruroAPI endpoints.

---

Table of Contents

• Health Check
• Stats
• Search
• Suggestions
• Filter
• Trending
• Popular
• Upcoming
• Recent
• Spotlight
• Schedule
• Anime Info
• Characters
• Relations
• Recommendations
• Episodes
• Watch (Streaming)

---

Health Check

GET /api/health

Returns API health status, version, uptime, memory usage, and available providers.

Response:

{
  "success": true,
  "results": {
    "status": "healthy",
    "version": "1.2.0",
    "uptime": "0h 0m 34s",
    "node": "v24.14.1",
    "memory": { "used": "13MB", "total": "15MB" },
    "endpoints": 16,
    "providers": ["kiwi","pewe","bee","bonk","bun","ally","nun","twin","cog","moo","hop","telli"]
  }
}

---

Stats

GET /api/stats

Returns request statistics, cache info, and memory usage.

---

Search

GET /api/search

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:

{
  "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"]
      }
    ]
  }
}

---

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:

{
  "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:

{
  "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:

{
  "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"
  }
}