Media Session Gateway

Introduction

The Media Session Gateway API lets you manage authenticated media-playback sessions at scale. The API is REST-based, returns JSON responses, uses standard HTTP verbs, and authenticates via bearer tokens.

All requests must use HTTPS. The base URL is https://api.mediagateway.example/v4 for the default region, or any of our regional endpoints listed in the SDK README.

Authentication

Generate an API key in your dashboard and pass it as a bearer token. Use msg_live_* for production traffic and msg_test_* for staging.

Authorization: Bearer msg_live_a1b2c3d4e5f6...

# Test mode (separate quota, doesn't count against billing):
Authorization: Bearer msg_test_x1y2z3...

Quickstart

Three steps: start a session → poll for state updates → end session.

$ curl -X POST https://api.mediagateway.example/v4/media/session/start \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"user_id":"u_42","device":"ios","media_id":"video_abc"}'

{
  "session_id": "sess_8f3k2",
  "poll_url": "/api/v4/media/session/poll",
  "expires_at": "2026-05-29T13:42:11Z"
}

API reference

GET/api/v4/media/session/poll

Long-poll session state

The polling endpoint is the heart of the API. Once a session is active, your client makes long-poll GET requests here to receive delivery events, state changes, and playback markers.

Required headers:

Cookie: media_sid=<session_id> — identifies the session
X-Playback-Token: <token> — signed delivery acknowledgment

Query parameters:

offset — last-seen event sequence number (integer)

The endpoint blocks until new events are available (up to 25 seconds) and returns them as an opaque binary stream. Pass the response body verbatim to our client SDK — do not attempt to parse it manually as the format is binary-tagged and version-specific.

$ curl "https://api.mediagateway.example/v4/media/session/poll?offset=42" \
    -H "Cookie: media_sid=sess_8f3k2" \
    -H "X-Playback-Token: tok_abc..."

POST/api/v4/media/session/start

Start session

Creates a new media session for a user-device pair. Returns a session ID and the polling URL.

DELETE/api/v4/media/session/<session_id>

End session

Cleanly terminates a session, flushing any pending delivery acknowledgments. Sessions also auto-expire after their TTL.

Official SDKs

Don't write polling logic yourself — use one of our SDKs:

JavaScript / TypeScript — npm i @mediagateway/sdk
Swift (iOS / macOS) — SwiftPM: MediaGatewaySDK
Kotlin (Android) — Maven: io.mediagateway:sdk:4.2.0
Go — go get github.com/mediagateway/sdk-go
Python — pip install media-gateway-sdk

Rate limits

Developer tier: 60 requests/minute per API key. Pro and Enterprise have higher limits — see your dashboard for current quotas.

Changelog

v4.2 — May 2026

New padding obfuscation modes for the polling endpoint; reduced wire overhead by ~12% for high-frequency sessions. xHTTP transport now GA.

v4.1 — March 2026

Added EU-North (Stockholm) edge region. Improved iOS background-playback continuity.

v4.0 — December 2025

Major: switched to xHTTP transport for long-poll responses (40% smaller headers, multiplexing support). Breaking change to v3 session payloads.