{ "openapi": "3.1.0", "info": { "title": "IPTV Nexus API", "version": "1.0.0", "description": "Self-updating IPTV channel, stream and EPG index with a free static API.\n\nThis is a **static** API: every endpoint is a pre-generated JSON file served over a CDN. There is no rate limit, no API key and no server. Every file also has a `.gz` sibling.\n\nGenerated at 2026-07-28T19:54:57.540Z.", "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://dearbulut.github.io/iptv", "description": "Static CDN" } ], "tags": [ { "name": "meta", "description": "Manifest and health reporting" }, { "name": "collections", "description": "Full collections" }, { "name": "shards", "description": "Pre-filtered slices for cheap client fetches" }, { "name": "detail", "description": "Single-resource documents" } ], "paths": { "/api/v1/index.json": { "get": { "summary": "API manifest: counts, endpoints and generation timestamp", "operationId": "getManifest", "tags": [ "meta" ], "responses": { "200": { "description": "API manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } } }, "/api/v1/channels.json": { "get": { "summary": "All channels with streams, health and EPG links", "operationId": "getChannels", "tags": [ "collections" ], "responses": { "200": { "description": "All channels with streams, health and EPG links", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } } } }, "/api/v1/streams.json": { "get": { "summary": "All streams, flattened", "operationId": "getStreams", "tags": [ "collections" ], "responses": { "200": { "description": "All streams, flattened", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Stream" } } } } } } } }, "/api/v1/countries.json": { "get": { "summary": "Countries with channel counts", "operationId": "getCountries", "tags": [ "collections" ], "responses": { "200": { "description": "Countries with channel counts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } } } } }, "/api/v1/languages.json": { "get": { "summary": "Languages with channel counts", "operationId": "getLanguages", "tags": [ "collections" ], "responses": { "200": { "description": "Languages with channel counts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } } } } } } }, "/api/v1/categories.json": { "get": { "summary": "Categories with channel counts", "operationId": "getCategories", "tags": [ "collections" ], "responses": { "200": { "description": "Categories with channel counts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } }, "/api/v1/regions.json": { "get": { "summary": "Geographic regions", "operationId": "getRegions", "tags": [ "collections" ], "responses": { "200": { "description": "Geographic regions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } } }, "/api/v1/subdivisions.json": { "get": { "summary": "Country subdivisions", "operationId": "getSubdivisions", "tags": [ "collections" ], "responses": { "200": { "description": "Country subdivisions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Subdivision" } } } } } } } }, "/api/v1/timezones.json": { "get": { "summary": "Timezones", "operationId": "getTimezones", "tags": [ "collections" ], "responses": { "200": { "description": "Timezones", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Timezone" } } } } } } } }, "/api/v1/guides.json": { "get": { "summary": "EPG guide links", "operationId": "getGuides", "tags": [ "collections" ], "responses": { "200": { "description": "EPG guide links", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Guide" } } } } } } } }, "/api/v1/health.json": { "get": { "summary": "Aggregate stream health report", "operationId": "getHealth", "tags": [ "meta" ], "responses": { "200": { "description": "Health report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReport" } } } } } } }, "/api/v1/search.json": { "get": { "summary": "Compact client-side search index", "operationId": "getSearchIndex", "tags": [ "meta" ], "responses": { "200": { "description": "Search index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchIndex" } } } } } } }, "/api/v1/channels/{channelId}.json": { "get": { "summary": "A single channel with all of its streams and guide links", "operationId": "getChannel", "tags": [ "detail" ], "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "BBCNews.uk" } ], "responses": { "200": { "description": "Channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "404": { "description": "Unknown channel" } } } }, "/api/v1/by-country/{key}.json": { "get": { "summary": "Channels filtered by country", "operationId": "getChannelsByCountry", "tags": [ "shards" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filtered channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } } } }, "/api/v1/by-category/{key}.json": { "get": { "summary": "Channels filtered by category", "operationId": "getChannelsByCategory", "tags": [ "shards" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filtered channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } } } }, "/api/v1/by-language/{key}.json": { "get": { "summary": "Channels filtered by language", "operationId": "getChannelsByLanguage", "tags": [ "shards" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filtered channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } } } }, "/epg/guide.xml.gz": { "get": { "summary": "Merged XMLTV guide for every linked channel (gzipped)", "operationId": "getGuide", "tags": [ "meta" ], "responses": { "200": { "description": "XMLTV document", "content": { "application/xml": {} } } } } }, "/playlists/index.m3u": { "get": { "summary": "Master M3U playlist", "operationId": "getPlaylist", "tags": [ "meta" ], "responses": { "200": { "description": "M3U playlist", "content": { "audio/x-mpegurl": {} } } } } } }, "components": { "schemas": { "Manifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "base_url": { "type": [ "string", "null" ] }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Channel": { "type": "object", "required": [ "id", "name", "country" ], "properties": { "id": { "type": "string", "example": "BBCNews.uk" }, "name": { "type": "string" }, "alt_names": { "type": "array", "items": { "type": "string" } }, "network": { "type": [ "string", "null" ] }, "owners": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string", "example": "GB" }, "categories": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "is_nsfw": { "type": "boolean" }, "launched": { "type": [ "string", "null" ] }, "closed": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Best rolling availability score across the channel’s streams" }, "online": { "type": "boolean" }, "streams": { "type": "array", "items": { "$ref": "#/components/schemas/Stream" } }, "guides": { "type": "array", "items": { "$ref": "#/components/schemas/Guide" } } } }, "Stream": { "type": "object", "required": [ "url" ], "properties": { "channel": { "type": [ "string", "null" ] }, "feed": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "referrer": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "quality": { "type": [ "string", "null" ], "example": "1080p" }, "rank": { "type": "number", "description": "Sort weight; higher is better" }, "health": { "$ref": "#/components/schemas/Health" } } }, "Health": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "online", "offline", "timeout", "blocked", "error", "unknown" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "checked_at": { "type": "string", "format": "date-time" }, "last_online": { "type": [ "string", "null" ], "format": "date-time" }, "latency_ms": { "type": [ "integer", "null" ] }, "uptime": { "type": "number", "description": "Uptime percentage over recorded history" }, "media": { "type": [ "object", "null" ], "properties": { "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "frame_rate": { "type": [ "number", "null" ] }, "bitrate": { "type": [ "integer", "null" ] }, "video_codec": { "type": [ "string", "null" ] }, "audio_codec": { "type": [ "string", "null" ] } } } } }, "Guide": { "type": "object", "properties": { "site": { "type": "string" }, "site_id": { "type": "string" }, "lang": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "method": { "type": "string", "enum": [ "upstream", "exact", "alias", "fuzzy", "manual" ] } } }, "Country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "flag": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "integer" }, "online": { "type": "integer" } } }, "Language": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "channels": { "type": "integer" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "channels": { "type": "integer" } } }, "Region": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } } } }, "Subdivision": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } } }, "Timezone": { "type": "object", "properties": { "id": { "type": "string" }, "utc_offset": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } } } }, "HealthReport": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "online": { "type": "integer" }, "offline": { "type": "integer" }, "healthy": { "type": "integer" }, "average_score": { "type": "number" }, "average_latency_ms": { "type": [ "integer", "null" ] }, "by_resolution": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "SearchIndex": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "fields": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "description": "Positional rows matching `fields`, for a compact payload", "items": { "type": "array" } } } } } } }