Public API

Cache-friendly, read-only JSON endpoints. No auth or API key required. Please be a good citizen — respect the cache headers, don't hammer the endpoints.

Ground rules

All endpoints return JSON with a top-level source field (db or fallback).
Cache-Control tells you the freshness window — please honor it.
Do not scrape or mirror the data. Link back to ALLtvLive instead.

GET/api/public/top

Top channels

Most-played channels aggregated from real viewer plays. Great for a leaderboard widget or a ‘trending now’ row on your site.

Cache-Control: s-maxage=60, stale-while-revalidate=300

Query parameters

rangeMs24h default · capped 30d— Look-back window in milliseconds
limit20 default · max 100— How many rows to return

Example request

curl https://alltvlive.example.com/api/public/top?rangeMs=86400000&limit=10

Response shape

{
  "channels": [
    {
      "channelId": "AlJazeeraEnglish.qa",
      "channelName": "Al Jazeera English",
      "plays": 214,
      "uniqueIps": 138,
      "lastPlayedAt": 1728820193000
    }
  ],
  "source": "db"
}

GET/api/public/health

Live stream health

Rolling success and failure counters per channel, aggregated across every viewer. Use it to surface a red / yellow / green dot on your own channel list.

Cache-Control: s-maxage=30, stale-while-revalidate=120

Example request

curl https://alltvlive.example.com/api/public/health

Response shape

{
  "channels": [
    {
      "channelId": "SkyNews.uk",
      "channelName": "Sky News",
      "status": "healthy",
      "failureRate": 0.02,
      "successes": 812,
      "failures": 17,
      "lastSuccessAt": 1728820193000,
      "lastFailureAt": 1728800001000
    }
  ],
  "source": "db"
}

Have questions? Open an issue on GitHub .