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.
- 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
-.
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": "…" }
}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.
Array of every channel. Large (~25 MB); prefer a shard or the search index for browser use.
Only channels whose last scan found a working stream.
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 | 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. |
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.
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.
| 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.
| 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.
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.
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
}
]
}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.
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.
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.
| 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.
A working stream for one channel
curl -s "$BASE/api/v1/channels/BBCNews.uk.json" \
| jq -r '.streams[] | select(.health.status=="online") | .url' | head -1Build 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.m3uWatch for channels that went dark
curl -s "$BASE/api/v1/channels.json" | jq '
[.[] | select(.stream_count > 0 and .online == false and .score > 0)]
| length'/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.