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.
46 endpoints, 12 streaming providers, M3U8 URLs with subtitles, skip timestamps, and batch operations.
Table of Contents •
Features •
API Docs •
Quick Start •
Deployment •
Contributing
---
> [!WARNING]
> 1. This `API` does not store any files β it only links to media hosted on 3rd party services.
> 2. This `API` is explicitly made for **educational purposes only** and not for commercial usage. This repo will not be responsible for any misuse of it.
> 3. All anime data, images, and content belong to their respective owners (AniList, Miruro). This project is not affiliated with Miruro.
---
## π Table of Contents
- [Overview](#-overview)
- [Features](#-features)
- [Data Sources](#-data-sources)
- [Tech Stack](#-tech-stack)
- [Architecture](#-architecture)
- [Project Structure](#-project-structure)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [API Endpoints](#-api-endpoints)
- [Streaming Flow](#-streaming-flow)
- [API Response Schema](#-api-response-schema)
- [Deployment](#-deployment)
- [Available Scripts](#-available-scripts)
- [Performance](#-performance)
- [Changelog Highlights](#-changelog-highlights)
- [Troubleshooting](#-troubleshooting)
- [FAQ](#-faq)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [Acknowledgements](#-acknowledgements)
- [License](#-license)
- [Author](#-author)
- [Star History](#-star-history)
---
## πΈ Overview
**MiruroAPI** is a serverless anime data API that fetches real-time information from **AniList GraphQL** and streaming data from **Miruro providers** β including anime details, episode lists, M3U8 streaming URLs with subtitles and skip timestamps, search, filtering, characters, and more β all through a clean REST API with zero database.
> π‘ No database, no auth, no complex setup. Just deploy to Vercel and you have a production API.
### Why MiruroAPI?
- π¬ **46 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
- π **Trending & Popular** β Discover what's hot right now
- π
**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
### π Self-Healing System (v2.3.0)
When Cloudflare blocks streaming requests, the API automatically tries fallback methods:
- **Direct** β Mirror rotation across 4 domains (miruro.to, miruro.ru, miruro.bz, miruro.tv)
- **ScraperAPI** β Free proxy bypass (1K req/month)
- **FlareSolverr** β Self-hosted browser proxy
Zero-config: works out of the box. Add `SCRAPER_API_KEY` env var for automatic Cloudflare bypass.
### β οΈ Streaming Status
> **Streaming endpoints (`/api/episodes`, `/api/watch`, `/api/sources`, `/api/stream`) return 500 errors when Cloudflare blocks pipe requests.**
>
> This is expected behavior on Vercel's free tier. Cloudflare's bot protection blocks requests from datacenter IPs (including Vercel's). Metadata endpoints (search, info, trending, etc.) work perfectly β only streaming is affected.
| What Works | What's Blocked |
|:---|:---|
| Search, suggestions, filter | Episodes, sources, stream |
| Info, characters, relations | Watch, download |
| Trending, popular, schedule | All pipe-dependent endpoints |
| Genres, tags, calendar | Streaming provider data |
| All AniList-backed endpoints | |
**To fix streaming**, set one of these environment variables in Vercel:
```bash
# Option 1: ScraperAPI (free 1K requests/month)
SCRAPER_API_KEY=your_scraperapi_key
# Option 2: FlareSolverr (self-hosted, unlimited)
FLARESOLVERR_URL=http://your-flaresolverr-host:8191
```
See [How to Fix Streaming](#-how-to-fix-streaming-issues) in Troubleshooting below.
### How It Works
```mermaid
flowchart TD
A["π Client Request
(Browser / App / curl)"] --> B["π‘οΈ Express Server
CORS Β· Security Headers Β· Rate Limiting"]
B --> C{"πΎ Cache Check
(In-Memory Map)"}
C -- HIT --> D["β‘ Return Cached Response
~50ms"]
C -- MISS --> E{"π Which Source?"}
E -- Metadata --> F["π‘ AniList GraphQL
graphql.anilist.co"]
E -- Streaming --> G["πΊ Miruro Pipe
miruro.{to,ru,bz,tv}/api/secure/pipe"]
F --> H["AniList Response
JSON"]
G --> I["Pipe Response
base64url + gzip"]
H --> J["Cache + Respond
JSON"]
I --> J
style A fill:#1e1e2e,stroke:#a78bfa,color:#f1f5f9
style B fill:#1e1e2e,stroke:#6366f1,color:#f1f5f9
style C fill:#1e1e2e,stroke:#f43f8e,color:#f1f5f9
style D fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
style E fill:#1e1e2e,stroke:#a855f7,color:#f1f5f9
style F fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9
style G fill:#1e1e2e,stroke:#eab308,color:#f1f5f9
style H fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9
style I fill:#1e1e2e,stroke:#eab308,color:#f1f5f9
style J fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
```
---
## β¨ Features
|
### β‘ Core
- **AniList GraphQL** for rich metadata
- **Miruro pipe** for streaming sources
- **Smart caching** with configurable TTL
- **46 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)
|
### π Data
- **Full-text search** with pagination
- **Autocomplete suggestions** for search
- **Advanced filtering** β genre, year, season, format, sort
- **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**
|
|
### π‘ Streaming
- **Episode lists** from 12 providers
- **M3U8 streaming URLs** with resolution info
- **Skip timestamps** (OP/ED)
- **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
|
### π‘οΈ Reliability
- **CORS enabled** β works from any frontend
- **Error responses** with descriptive messages
- **Input validation** β required params checked
- **Timeout protection** β per request
- **In-memory caching** β survives warm starts
- **Zero database** β pure API + cache
|
### π Feature Highlights
| Feature | Description | Status |
|:---|:---|:---:|
| π¬ 46 API Endpoints | Complete anime data coverage | β
|
| π Full-Text Search | Keyword search with pagination | β
|
| π‘ Search Suggestions | Fast autocomplete | β
|
| π― Advanced Filtering | Genre, year, season, format, sort | β
|
| π Characters + Voice Actors | Full character data from AniList | β
|
| π Relations & Recommendations | Related anime discovery | β
|
| βοΈ Skip Timestamps | OP/ED skip data | β
|
| π‘ 12 Streaming Providers | M3U8 streaming sources | β
|
| π Smart Caching | In-memory Map with TTL | β
|
| π One-Click Deploy | Vercel button deployment | β
|
| ποΈ Express Mode | Standalone server with `npm start` | β
|
| π³ Docker Support | Containerized deployment | β
|
---
## ποΈ Data Sources
### Metadata Source
| Source | API | Data |
|:---|:---|:---|
| πΈ **AniList** | `graphql.anilist.co` | Search, info, characters, relations, recommendations, filter, schedule |
### Streaming Source
| Source | Domain | Data |
|:---|:---|:---|
| πΊ **Miruro** | `miruro.to` | Episodes, streaming sources (M3U8 URLs) |
| πΊ **Miruro** | `miruro.ru` | Mirror domain |
| πΊ **Miruro** | `miruro.bz` | Mirror domain |
| πΊ **Miruro** | `miruro.tv` | Mirror domain |
### π¬ Streaming Providers
| Provider | Provider | Provider | Provider |
|:---|:---|:---|:---|
| π₯ kiwi | π pewe | π» bee | π― bonk |
| π bun | π€ ally | π¦ nun | π― twin |
| βοΈ cog | π moo | π° hop | πΊ telli |
---
## π οΈ Tech Stack
| Technology | Purpose | Version | Documentation |
|:---|:---|:---|:---|
| π’ [Node.js](https://nodejs.org/) | JavaScript runtime | >= 20 | [Docs](https://nodejs.org/docs/) |
| β‘ [Express](https://expressjs.com/) | HTTP server framework | 4.21 | [Docs](https://expressjs.com/en/4x/api.html) |
| β² [Vercel Functions](https://vercel.com/docs/functions) | Serverless deployment | β | [Docs](https://vercel.com/docs/functions) |
| πΈ [AniList GraphQL](https://anilist.gitbook.io/anilist-apiv2-docs/) | Anime metadata API | β | [Docs](https://anilist.gitbook.io/anilist-apiv2-docs/) |
| π [Axios](https://axios-http.com/) | HTTP client | 1.8 | [Docs](https://axios-http.com/docs/intro) |
| π§ [dotenv](https://github.com/motdotla/dotenv) | Environment variables | 16.4 | [Docs](https://github.com/motdotla/dotenv) |
| π [cors](https://github.com/expressjs/cors) | CORS middleware | 2.8 | [Docs](https://github.com/expressjs/cors) |
### π¦ Key Dependencies
```json
{
"express": "^4.21.0", // HTTP server
"axios": "^1.8.0", // HTTP client
"cors": "^2.8.5", // CORS middleware
"dotenv": "^16.4.0" // Environment variables
}
```
---
## ποΈ Architecture
### Request Flow
| Stage | Component | Description |
|:-----:|-----------|-------------|
| 1 | **Client** | Browser, app, or `curl` sends request |
| 2 | **Express Server** | Routes request, applies CORS + security headers + rate limiting |
| 3 | **Cache Check** | In-memory Map with TTL β hit = instant response |
| 4 | **Fetch Data** | AniList GraphQL or Miruro pipe endpoint |
| 5 | **Decode** | Pipe responses decoded: base64url β gunzip β JSON |
| 6 | **Cache + Respond** | Store in cache, return JSON response |
### Caching Architecture
```mermaid
flowchart TD
A["π₯ Request"] --> B{"π§ Memory Cache
(Map + TTL)"}
B -- HIT --> C["β‘ Return Cached
~50ms"]
B -- MISS --> D["π‘ Fetch from
AniList / Miruro"]
D --> E["π Decode
base64url + gzip"]
E --> F["πΎ Cache Result
(1-5 min TTL)"]
F --> G["π€ Return Fresh"]
style A fill:#1e1e2e,stroke:#a78bfa,color:#f1f5f9
style B fill:#1e1e2e,stroke:#f43f8e,color:#f1f5f9
style C fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
style D fill:#1e1e2e,stroke:#6366f1,color:#f1f5f9
style E fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9
style F fill:#1e1e2e,stroke:#a855f7,color:#f1f5f9
style G fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
```
> π‘ Serverless functions have read-only filesystems except `/tmp`. The cache uses in-memory `Map` which survives across warm invocations.
---
## π Project Structure
```
MiruroAPI/
βββ π public/ # π Static files
β βββ π index.html # π Premium landing page (real Miruro icons)
β βββ π docs.html # π Swagger UI interactive documentation
β βββ π openapi.json # π OpenAPI 3.0 spec
β βββ π icon-dark.svg # π Miruro dark mode favicon
β βββ π icon-light.svg # βοΈ Miruro light mode favicon
β βββ π icon-512x512.png # π± Miruro app icon
β βββ π favicon.ico # π Classic favicon
β βββ π apple-touch-icon-180x180.png # π iOS home screen icon
β βββ π og-image.png # πΌοΈ OG/Twitter share image
β
βββ π assets/ # π¨ Scraped Miruro assets
β βββ π favicons/ # π All favicon variants
β βββ π logos/ # π·οΈ Status page logo
β βββ π fonts/ # π€ Inter + FontAwesome
β βββ π media/ # πΌοΈ Testimonial avatars
β
βββ π src/ # βοΈ Core logic
β βββ π helpers/ # π οΈ Integration modules
β β βββ π anilist.js # πΈ AniList GraphQL integration
β β βββ π pipe.js # πΊ Miruro pipe integration
β β βββ π cache.js # πΎ In-memory cache with TTL
β β
β βββ π routes/ # π€οΈ Express routes
β βββ π apiRoutes.js # π Main API routes (46 endpoints)
β
βββ π server.js # π Express server entry point
βββ π package.json # π¦ Dependencies & scripts
βββ π vercel.json # β² Vercel routing config
βββ π Dockerfile # π³ Docker support
βββ π .dockerignore # π³ Docker ignore
βββ π CHANGELOG.md # π Version history
βββ π README.md # π This file
```
---
## π Quick Start
### Prerequisites
| Requirement | Minimum | Recommended |
|:---|:---|:---|
| π¦ Node.js | 20.x | 20.x LTS |
| π¦ npm | 9.0+ | 10.x |
| π» OS | Windows, macOS, Linux | Any |
### π§ Installation
```bash
# 1οΈβ£ Clone the repository
git clone https://github.com/Shineii86/MiruroAPI.git
cd MiruroAPI
# 2οΈβ£ Install dependencies
npm install
# 3οΈβ£ Start development server
npm run dev
```
> π Open [http://localhost:3000](http://localhost:3000) in your browser.
### ποΈ Build for Production
```bash
# Start production server
npm start
```
### π³ Alternative Package Managers
```bash
# Using yarn
yarn install
yarn dev
# Using pnpm
pnpm install
pnpm dev
# Using bun
bun install
bun dev
```
---
## βοΈ Configuration
### Environment Variables
| Variable | Default | Description |
|:---|:---|:---|
| `PORT` | `3000` | Server port (Express mode only) |
| `ALLOWED_ORIGINS` | `*` | Comma-separated allowed origins (restricts CORS in production) |
| `PIPE_OBF_KEY` | `71951034...` | Pipe response XOR obfuscation key (hex, 32 chars) |
| `PRU_PROXY_KEY` | `a54d389c...` | PRU proxy URL XOR key (hex, 32 chars) |
| `SCRAPER_API_KEY` | β | ScraperAPI key for Cloudflare bypass (free 1K req/month) |
| `FLARESOLVERR_URL` | β | FlareSolverr URL for browser-based bypass (e.g., `http://127.0.0.1:8191`) |
> β οΈ **Required for production:** Set `ALLOWED_ORIGINS` to restrict CORS. Set `PIPE_OBF_KEY` and `PRU_PROXY_KEY` for pipe decoding.
>
> πΊ **For streaming:** Set `SCRAPER_API_KEY` or `FLARESOLVERR_URL` to bypass Cloudflare bot protection. See [How to Fix Streaming Issues](#-how-to-fix-streaming-issues).
### Vercel Configuration
The `vercel.json` file handles:
- **Builds** β Maps `server.js` to `@vercel/node`
- **Routes** β All requests forwarded to Express
---
## π‘ API Endpoints
### Base URL
```
https://mirurotvapi.vercel.app/api
```
### Response Format
All endpoints return:
```json
{
"success": true,
"results": { ... }
}
```
### Streaming Flow
To get a stream URL, follow these 3 steps:
```bash
# Step 1: Get episodes (returns provider slugs)
curl "https://mirurotvapi.vercel.app/api/episodes/20"
# Step 2: Get streaming sources (pass provider + anilistId + category + slug)
curl "https://mirurotvapi.vercel.app/api/watch/kiwi/20/sub/animepahe-1"
# Step 3: Play M3U8 in any HLS player
# Use hls.js, video.js, or native