Streaming API

Endpoints for obtaining stream URLs and proxying media requests.

Get Stream URL

GET /api/providers/:id/channels/:channel_id/stream

Returns the stream URL, type, and optional DRM information for a specific channel.

Headers:

Authorization: Bearer <jwt_token>

Path Parameters:

Parameter	Description
id	Provider identifier
channel_id	Channel identifier

Response (HLS — No DRM)

Response: 200 OK

{
  "url": "/api/proxy?url=https%3A%2F%2Fcdn.example.com%2Flive%2Fch001.m3u8&ctx=abc123",
  "stream_type": "hls",
  "drm": null
}

Response (DASH + DRM)

Response: 200 OK

{
  "url": "/api/proxy?url=https%3A%2F%2Fcdn.example.com%2Flive%2Fch001.mpd&ctx=abc123",
  "stream_type": "dash",
  "drm": {
    "system": "widevine",
    "license_url": "https://license.example.com/widevine",
    "headers": {
      "Authorization": "Bearer provider_token_here",
      "X-Custom-Data": "user123"
    }
  }
}

Stream Info Object

Field	Type	Description
url	string	Stream URL (proxied through /api/proxy)
stream_type	string	"hls" or "dash"
drm	object | null	DRM configuration (null for clear streams)

DRM Object

Field	Type	Description
system	string	DRM system: "widevine" or "playready"
license_url	string	License server URL
headers	object	Headers to include in license requests

Error Responses:

Status	Condition
400	Provider API returned an error
401	Missing or invalid JWT token
404	Provider not found or no active session

Stream Proxy

GET /api/proxy?url=<encoded_url>&ctx=<token>

Proxies media requests (manifests, segments, keys) to upstream CDN servers with appropriate headers, cookies, and authentication.

No authentication required — the ctx token contains the necessary context.

Query Parameters:

Parameter	Description
url	URL-encoded upstream URL to fetch
ctx	Proxy context token (generated by the stream endpoint)

Behavior

1. Looks up the proxy context using the ctx token.
2. Injects configured headers and cookies.
3. Converts URL parameters to cookies (if configured).
4. For .m3u8 playlists, rewrites relative URLs to proxy URLs.
5. Returns the upstream response with appropriate content-type headers.

Response

The response mirrors the upstream CDN response:

• For manifests (.m3u8): rewritten playlist content
• For segments (.ts): binary video data
• For keys (.key): encryption key data

Error Responses:

Status	Condition
400	Missing url or ctx parameter
404	Invalid or expired proxy context
502	Upstream CDN error