Skip to content

Latest commit

 

History

History
395 lines (316 loc) · 13.2 KB

API.md

File metadata and controls

395 lines (316 loc) · 13.2 KB

API reference

The API is static: every endpoint is a file generated by CI and served from a CDN. There is no key, no rate limit, no server and no cost. GET is the only verb; CORS is open.

Machine-readable schema: /api/v1/openapi.json (generated at build time).

Throughout, BASE is your deployment root, e.g. https://dearbulut.github.io/iptv.

Conventions

  • All timestamps are ISO-8601 UTC.
  • Country codes are ISO 3166-1 alpha-2 uppercase in documents, lowercase in shard paths (/by-country/tr.json).
  • Language codes are ISO 639-3 (eng, tur, deu).
  • Any document larger than 32 KB also exists as <name>.json.gz.
  • Shard paths are slugified: lowercase, non-alphanumerics collapsed to -.

Meta

GET /api/v1/index.json

The manifest. Fetch this first — it tells you what exists and when it was built.

{
  "name": "IPTV Nexus",
  "version": "1.0.0",
  "generated_at": "2026-07-26T18:00:00.000Z",
  "base_url": "https://dearbulut.github.io/iptv",
  "counts": {
    "channels": 39421,
    "online_channels": 8214,
    "streams": 15451,
    "online_streams": 9033,
    "epg_programmes": 412903,
    "countries": 214,
    "languages": 137,
    "categories": 24
  },
  "endpoints": { "channels": "…/api/v1/channels.json", "...": "…" },
  "upstream": { "source": "https://iptv-org.github.io/api", "fetched_at": "…" }
}

GET /api/v1/health.json

Aggregate health across every tracked stream.

{
  "generated_at": "2026-07-26T18:00:00.000Z",
  "total": 15451,
  "online": 9033,
  "offline": 4102,
  "blocked": 1980,
  "timeout": 336,
  "healthy": 9600,
  "retired": 214,
  "average_score": 61.4,
  "average_latency_ms": 486,
  "by_resolution": { "1080p": 5210, "720p": 4890, "576p": 1204 },
  "by_country": { "TR": { "channels": 417, "online": 190 } }
}

blocked counts geo-restrictions observed from the CI runner. Those results are recorded but excluded from scoring — a channel that is simply unavailable in the runner's region is not a broken channel.


Channels

GET /api/v1/channels.json

Array of every channel. Large (~25 MB); prefer a shard or the search index for browser use.

GET /api/v1/channels.online.json

Only channels whose last scan found a working stream.

GET /api/v1/channels/{id}.json

One channel. By default only channels with at least one stream have a detail document (api.channel_details: playable).

{
  "id": "BBCNews.uk",
  "name": "BBC News",
  "alt_names": ["BBC News Channel"],
  "network": "BBC",
  "owners": ["British Broadcasting Corporation"],
  "country": "GB",
  "subdivision": null,
  "categories": ["news"],
  "languages": ["eng"],
  "broadcast_area": ["c/GB"],
  "timezones": ["Europe/London"],
  "is_nsfw": false,
  "launched": "1997-11-09",
  "closed": null,
  "replaced_by": null,
  "website": "https://www.bbc.co.uk/news",
  "logo": "https://…/bbcnews.png",
  "score": 92,
  "online": true,
  "availability": "online",
  "number": 1873,
  "stream_count": 3,
  "browser_playable": true,
  "best_quality": "1080p",
  "streams": [
    {
      "channel": "BBCNews.uk",
      "feed": null,
      "title": "BBC News",
      "url": "https://…/index.m3u8",
      "referrer": null,
      "user_agent": null,
      "quality": "1080p",
      "rank": 84.2,
      "sources": ["iptv-org"],
      "browser_playable": true,
      "browser_blocker": null,
      "health": {
        "status": "online",
        "score": 92,
        "uptime": 96.7,
        "history": "111111110111111111111111111111",
        "checked_at": "2026-07-26T15:02:11.000Z",
        "last_online": "2026-07-26T15:02:11.000Z",
        "latency_ms": 210,
        "media": {
          "width": 1920, "height": 1080, "resolution": "1080p",
          "frame_rate": 25, "bitrate": 3200000,
          "video_codec": "h264", "audio_codec": "aac", "variants": 4
        }
      }
    }
  ],
  "guides": [
    { "site": "bbc.co.uk", "site_id": "bbcnews", "lang": "en",
      "confidence": 1, "method": "upstream" }
  ]
}

Field notes

Field Meaning
score Best rolling availability score across the channel's streams, 0–100. 0 means "not conclusively checked yet", not "broken" — check streams[].health to tell the difference.
online At least one stream responded on the most recent scan.
availability online, regional (nothing answered, but a stream refused our scanner with a geo-block — it may well work where you are), offline, unchecked or none (no stream).
number Permanent channel number, also emitted as tvg-chno in playlists. Never changes and is never reused. null for channels without a stream.
browser_playable At least one stream can play on an HTTPS web page.
streams[].browser_playable / browser_blocker Whether this stream plays in a browser, and if not why: insecure (plain http://, blocked as mixed content), headers (needs Referer/User-Agent) or format (.ts, DASH, RTMP…). Such streams still work in VLC, Kodi, TiviMate and similar.
streams[].health.history Recorded checks, oldest first: 1 up, 0 down.
streams[].rank Sort weight combining health, quality, latency and source trust. Streams are pre-sorted best-first; you can just take streams[0].
streams[].sources Which configured sources contributed this URL.
streams[].health.uptime Percentage of recorded checks that succeeded.
streams[].referrer / user_agent If set, the stream requires these headers. Browsers cannot set them — such streams generally need VLC or a native player.
guides[].method upstream and exact are authoritative; fuzzy was inferred and carries a confidence in 0–1.

Shards

Pre-filtered slices, so a client fetches kilobytes instead of megabytes.

Path Example
/api/v1/by-country/{code}.json /by-country/tr.json
/api/v1/by-category/{id}.json /by-category/sports.json
/api/v1/by-language/{code}.json /by-language/tur.json

Each returns the same channel objects as channels.json.

Available keys come from countries.json, categories.json and languages.json, which carry channels and online counts — enough to build a filter UI without touching the channel list.


Search index

GET /api/v1/search.json

A compact index for offline, client-side search. Rows are positional arrays rather than objects, which cuts the payload by roughly two thirds.

{
  "generated_at": "…",
  "fields": ["id","name","search","country","categories",
             "languages","logo","score","online","streams","quality"],
  "count": 39421,
  "channels": [
    ["BBCNews.uk","BBC News","bbcnews bbcnewschannel","GB","news",
     "eng","https://…png",92,1,3,"1080p"]
  ]
}

Read positions from fields rather than hard-coding them. Index 2 is a normalised blob (lowercased, diacritics stripped, spaces and punctuation removed) — normalise the query the same way and a single indexOf is enough.

Rows are pre-sorted: online first, then by score, then by name. Slicing the head gives you sensible "top results" for free.


Playlists

Path Contents
/playlists/index.m3u Every stream of every channel
/playlists/best.m3u One best stream per channel
/playlists/online.m3u Only streams above the healthy threshold
/playlists/country/{code}.m3u Per country
/playlists/category/{id}.m3u Per category
/playlists/language/{code}.m3u Per language
/api/v1/playlists.json Index of every generated playlist

Entries are ordered by channel number and carry tvg-chno, tvg-id (the Nexus id, matching the guide), group-title and, where a stream needs them, #EXTVLCOPT:http-referrer / http-user-agent lines. Country playlists point x-tvg-url at that country's own guide shard, so a TV app downloads only the guide it needs; the rest point at the merged guide.

Entries carry standard tvg-id, tvg-name, tvg-logo, tvg-country, tvg-language and group-title attributes, plus a non-standard nexus-score holding the health score. The #EXTM3U header sets x-tvg-url to the merged guide, so most players pick up EPG automatically.

Streams that need custom headers emit #EXTVLCOPT:http-user-agent and #EXTVLCOPT:http-referrer lines.


EPG

Path Contents
/epg/guide.xml, /epg/guide.xml.gz Merged guide for every linked channel
/epg/{country}.xml[.gz] Per-country guide

Standard XMLTV. Channel ids are Nexus channel ids, matching tvg-id in the playlists and id in the API — that is the whole point of the matching stage, and it means one guide URL works for every playlist.

GET /api/v1/epg-unmatched.json

Guide channels that no rule could link to a Nexus channel, grouped by guide:

{
  "total": 1067,
  "by_site": { "pluto-tv": 410, "mi-tv": 316 },
  "channels": [{ "site": "tvplus-com-tr", "site_id": "4355", "name": "EKOL TV" }]
}

A fix is one entry in config/epg-overrides.yml — { site, site_id, channel } to link it, or { site, site_id, skip: true } for a channel we do not carry.

Changes

GET /api/v1/changes.json · GET /api/v1/changes.xml

Channels that became watchable (gained their first stream) or stopped being watchable, one entry per build that changed something, newest first, up to 120 entries. changes.xml is the same as an Atom feed. Online/offline flapping of individual streams is not included; see health.json.

{
  "version": 1,
  "entries": [
    {
      "at": "2026-11-17T12:23:44.401Z",
      "added": [{ "id": "TRT1.tr", "name": "TRT 1", "country": "TR" }],
      "removed": [],
      "playable": 10469
    }
  ]
}

GET /api/v1/regional.json

Where each channel works, by viewer country, over the last 14 days:

{ "channels": { "TRT1.tr": { "TR": { "ok": 41, "fail": 1, "ratio": 0.98 }, "DE": { "ok": 2, "fail": 9, "ratio": 0.18 } } } }

Counts come from the Worker: channel streams tested from the Cloudflare location nearest each viewer, plus successful plays in the web player. The same data is on each channel as regional. Only the viewer's country is recorded.

GET /api/v1/vod.json

Free films and series: Internet Archive items whose licence is a public-domain dedication or a Creative Commons licence. Published once the weekly VOD Catalogue workflow has built a catalogue (404 before that).

{
  "generated_at": "2026-11-23T05:52:10.000Z",
  "counts": { "movies": 2800, "series": 120, "episodes": 2100 },
  "movies": [
    {
      "id": "night_of_the_living_dead",
      "number": 17,
      "title": "Night of the Living Dead",
      "year": 1968,
      "categories": ["Feature Films", "Sci-Fi & Horror"],
      "license": { "label": "Public Domain", "url": "https://creativecommons.org/publicdomain/mark/1.0/" },
      "poster": "https://archive.org/services/img/night_of_the_living_dead",
      "url": "https://archive.org/download/night_of_the_living_dead/night_of_the_living_dead.mp4",
      "runtime": 5747,
      "source_url": "https://archive.org/details/night_of_the_living_dead"
    }
  ],
  "series": [{ "id": "…", "number": 40, "title": "…", "episodes": [{ "id": "…-e1", "number": 41, "episode": 1, "title": "…", "url": "…", "runtime": 1510 }] }]
}

number is permanent and never reused; it is the Xtream stream_id, series_id and episode id. id is the archive.org identifier. Videos play straight from archive.org (MP4, H.264 where available). The same titles are in /playlists/vod/movies.m3u, /playlists/vod/series.m3u, the Stremio addon (movie and series types, ids prefixed nexusvod-) and /xtream/vod.json.

GET /epg/channels/{id}.json

One channel's guide from three hours ago to 48 hours ahead — enough for "now / next" without downloading the merged guide. 404 when the guide has no programmes for the channel.

Clients

Path Contents
/api/v1/match.json Every channel's id, name, aliases, country, logo, number, state and guide flag as positional rows; what the browser playlist fixer uses
/stremio/manifest.json Static Stremio addon — install this URL in Stremio
/xtream/index.json · /xtream/vod.json Data behind the Xtream Codes Worker (workers/xtream)

Setup for Jellyfin, Plex, Kodi, TiviMate, Stremio and others: CLIENTS.md.


Recipes

A working stream for one channel

curl -s "$BASE/api/v1/channels/BBCNews.uk.json" \
  | jq -r '.streams[] | select(.health.status=="online") | .url' | head -1

Build a personal playlist of healthy HD sports channels

curl -s "$BASE/api/v1/by-category/sports.json" | jq -r '
  "#EXTM3U",
  (.[] | select(.online and (.best_quality|test("1080|2160")))
       | "#EXTINF:-1 tvg-id=\"\(.id)\" tvg-logo=\"\(.logo)\",\(.name)",
         .streams[0].url)' > sports.m3u

Watch for channels that went dark

curl -s "$BASE/api/v1/channels.json" | jq '
  [.[] | select(.stream_count > 0 and .online == false and .score > 0)]
  | length'

Stability

/api/v1/** is versioned. Fields are added, not removed or repurposed; a breaking change would ship as /api/v2/. generated_at in the manifest tells you how fresh the data is — with the default schedule, at most 6 hours old.