xOTTNative player API and compatibility outputs
Use the real versioned API, its OpenAPI reference and the public SDK—not internal staff endpoints.
On this page
Choose the correct API
| Interface | Who uses it |
|---|---|
| Native Player API: /api/player/v1 | Access-line clients: channels, events, VOD, guide, playback and personal state. |
| M3U / XMLTV / Xtream-compatible gateway | Compatible third-party players using the line’s generated access details. |
| Access management API | Authorized staff/reseller integrations with their own scoped authentication—not player bearer tokens. |
| Provider service adapters | Internal source acquisition; not the public subscriber API. |
The instance’s /api/player/v1/openapi.json is the current native contract. Access-management OpenAPI is exposed through its separately authenticated /api/access/openapi.json route. Source-generated reference snapshots are available here: Player OpenAPI and Access OpenAPI. Your installed version takes precedence.
Authenticate with access-line credentials
POST /api/player/v1/auth/token
Content-Type: application/json
{"username":"demo-line","password":"REPLACE_ME","deviceId":"client-device-1"}Use HTTPS, protect access and refresh tokens, and rotate refresh tokens serially. Persist the replacement refresh token atomically. Never embed staff credentials or provider secrets in a player. Browser clients should use the supported same-origin web-auth flow/SDK rather than invent a token-storage scheme.
Discover capabilities and catalogue
| Method / route | Purpose |
|---|---|
| GET /capabilities and /me | Subscription rights, feature support, expiry and connection allowance. |
| GET /channels, /events, /event-slots | Authorized channels and event snapshots; native events and permanent slots remain distinct. |
| GET /movies, /series, /recordings | Authorized published media. |
| GET /series/:id/episodes | Published episodes for a series. |
| POST /guide | Bounded guide window for up to 40 channel IDs. |
| GET /changes | Catalogue/entitlement versions; discard stale caches when resetRequired. |
Routes in this table are relative to /api/player/v1. Paginated lists use opaque cursors and limits up to 100. Follow nextCursor; do not manufacture offsets or parse the cursor.
Admit, renew and release playback
POST /api/player/v1/playback
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{"type":"channel","id":"CHANNEL_ID","format":"hls"}Supported resource types include channel, event, event_slot and vod. Use the granted URL and renewal instructions, not a saved provider manifest. Live formats include HLS/MPEG-TS; current VOD delivery uses files with byte-range seeking.
- Keep active leases alive at the server-provided heartbeat interval.
- Use the provided session nonce/generation when releasing native playback so a stale tab cannot release newer playback.
- Handle revocation and capacity denial; do not retry failed authentication or a denied grant in a tight loop.
- Use the public SDK at
/api/player/v1/sdk.jswhere appropriate.
Personal state and errors
Favourites, playback progress, sessions and devices have dedicated routes. Progress updates include a revision to reject stale writes. Quality-of-experience reports are client observations, not authoritative billable traffic totals.
Errors use structured problem responses and a request reference. Inspect HTTP status: 401 may require authentication refresh; 403 is a policy denial; 404 can mean unavailable or unauthorized content; 429 means back off; 503 means temporary failure. Do not expose raw upstream secrets in diagnostics.
M3U and Xtream clients
Copy the server, username/password and playlist/guide details shown on the Access Line. Compatibility APIs are not the internal administration API. Visibility follows that line’s entitlements and output profile. Not every Xtream client presents series, recordings, categories or subtitles identically; validate the client you actually distribute.