{
  "openapi": "3.0.3",
  "info": {
    "title": "MiruroAPI",
    "description": "Free RESTful API for anime streaming data. Powered by AniList GraphQL and Miruro streaming providers.",
    "version": "2.3.0",
    "contact": {
      "name": "Shineii86",
      "url": "https://github.com/Shineii86/MiruroAPI"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://mirurotvapi.vercel.app",
      "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/search": {
      "get": {
        "tags": ["Search"],
        "summary": "Search anime by name",
        "parameters": [
          { "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 } }
        ]
      }
    },
    "/api/suggestions": {
      "get": {
        "tags": ["Search"],
        "summary": "Autocomplete suggestions",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }
        ]
      }
    },
    "/api/filter": {
      "get": {
        "tags": ["Search"],
        "summary": "Advanced filter",
        "parameters": [
          { "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"] } },
          { "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 } }
        ]
      }
    },
    "/api/multi-search": {
      "get": {
        "tags": ["Search"],
        "summary": "Multi-parameter search"
      }
    },
    "/api/trending": {
      "get": {
        "tags": ["Collections"],
        "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"
      }
    },
    "/api/top": {
      "get": {
        "tags": ["Collections"],
        "summary": "Top anime by score"
      }
    },
    "/api/upcoming": {
      "get": {
        "tags": ["Collections"],
        "summary": "Upcoming anime"
      }
    },
    "/api/recent": {
      "get": {
        "tags": ["Collections"],
        "summary": "Recently aired anime"
      }
    },
    "/api/spotlight": {
      "get": {
        "tags": ["Collections"],
        "summary": "Spotlight/featured anime"
      }
    },
    "/api/schedule": {
      "get": {
        "tags": ["Collections"],
        "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": "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",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ]
      }
    },
    "/api/anime/{id}/characters": {
      "get": {
        "tags": ["Anime Details"],
        "summary": "Characters",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ]
      }
    },
    "/api/anime/{id}/relations": {
      "get": {
        "tags": ["Anime Details"],
        "summary": "Relations",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ]
      }
    },
    "/api/anime/{id}/recommendations": {
      "get": {
        "tags": ["Anime Details"],
        "summary": "Recommendations",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ]
      }
    },
    "/api/episodes/{id}": {
      "get": {
        "tags": ["Streaming"],
        "summary": "Episode list",
        "parameters": [
          { "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)",
        "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", "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) with subtitles",
        "description": "Returns streaming sources, subtitles (if available), and best stream with quality fallback",
        "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" } },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "results": {
                      "type": "object",
                      "properties": {
                        "streams": { "type": "array" },
                        "download": { "type": "string" },
                        "subtitles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "url": { "type": "string", "description": "VTT subtitle file URL" },
                              "label": { "type": "string", "description": "Display name" },
                              "language": { "type": "string", "description": "Language code" },
                              "kind": { "type": "string", "description": "subtitles or captions" },
                              "format": { "type": "string", "description": "vtt format" },
                              "encoding": { "type": "string", "description": "utf-8" },
                              "isDefault": { "type": "boolean", "description": "Is default subtitle" }
                            }
                          }
                        },
                        "bestStream": { "type": "object" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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/providers": {
      "get": {
        "tags": ["System"],
        "summary": "Available streaming providers"
      }
    },
    "/api/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check"
      }
    },
    "/api/pipe-health": {
      "get": {
        "tags": ["System"],
        "summary": "Pipe fallback method health check"
      }
    },
    "/api/stats": {
      "get": {
        "tags": ["System"],
        "summary": "API statistics"
      }
    },
    "/api/openapi": {
      "get": {
        "tags": ["System"],
        "summary": "OpenAPI spec"
      }
    }
  }
}