{
  "name": "ColorOS TV Hub API",
  "version": "1.0.0",
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/m3u",
      "summary": "Parse a remote M3U / M3U8 playlist into structured JSON.",
      "params": [
        {
          "name": "url",
          "required": true,
          "desc": "Absolute URL of the .m3u / .m3u8 source."
        },
        {
          "name": "group",
          "required": false,
          "desc": "Filter channels by group-title (case-insensitive, partial match)."
        },
        {
          "name": "q",
          "required": false,
          "desc": "Free-text search across channel names (partial match)."
        },
        {
          "name": "limit",
          "required": false,
          "desc": "Max number of channels returned (default 500, max 2000)."
        }
      ],
      "example": "/api/m3u?url=https%3A%2F%2Fraw.githubusercontent.com%2FYueChan%2FLive%2Fmain%2FIPTV.m3u",
      "returns": "{ source, total, matched, returned, groups[], channels[{name,logo,group,url,tvg}] }"
    },
    {
      "method": "GET",
      "path": "/api/groups",
      "summary": "Return only the distinct group-title list of a playlist.",
      "params": [
        {
          "name": "url",
          "required": true,
          "desc": "Absolute URL of the .m3u source."
        }
      ],
      "example": "/api/groups?url=https%3A%2F%2Fraw.githubusercontent.com%2FYueChan%2FLive%2Fmain%2FIPTV.m3u",
      "returns": "{ source, count, groups[] }"
    },
    {
      "method": "GET",
      "path": "/api/stream",
      "summary": "Server-side stream proxy. Fetches a media/playlist URL and returns it same-origin (fixes ERR_BLOCKED_BY_ORB and CORS). HLS manifests are rewritten so segments/keys also load same-origin.",
      "params": [
        {
          "name": "url",
          "required": true,
          "desc": "Absolute URL of the media/playlist (may already be a proxy URL)."
        },
        {
          "name": "base",
          "required": false,
          "desc": "Original source URL; used to resolve relative URIs inside HLS manifests."
        },
        {
          "name": "px",
          "required": false,
          "desc": "Proxy prefix applied to inner segment/key URIs."
        }
      ],
      "example": "/api/stream?url=https%3A%2F%2Fexample.com%2Fplaylist.m3u8",
      "returns": "Raw media bytes or rewritten HLS playlist (same-origin)."
    },
    {
      "method": "GET",
      "path": "/api/docs",
      "summary": "Return this API documentation as JSON.",
      "params": [],
      "example": "/api/docs",
      "returns": "{ name, version, endpoints[] }"
    }
  ]
}