Skip to main content
After you send playback writes, use these endpoints to read the latest materialized state.

​
Required scopes

  • /api/platform/v1/playback/now-playing requires playback:read
  • /api/platform/v1/playback/in-progress requires playback:read
  • /api/platform/v1/me/continue-watching requires playback:read
  • DELETE /api/platform/v1/playback/in-progress/{id} requires playback:write
  • /api/platform/v1/playback/events requires events:read

​
Now Playing

Use this when you need the single most relevant active playback item for the user. Common response fields:
  • type
  • tmdbId
  • title
  • progressPercent
  • progressSeconds
  • durationSeconds
  • nowPlaying
  • playbackState
  • mediaSource

​
In Progress

Use this when you need a queue of active or resumable items rather than a single now-playing object. Dismiss an item with:

​
Continue Watching

Use this for the user’s movie and episode progress. Fetch /api/platform/v1/me/continue-watching/{showId} when you need a show’s current season and episode details.

​
Server-sent events

The stream sends lightweight notifications whenever playback state changes. Event types:
  • ready
  • playback-update
playback-update includes:
Use SSE as an invalidation signal, not as the full source of truth.
  1. Open the event stream.
  2. Wait for playback-update.
  3. Fetch /playback/now-playing or /playback/in-progress.
  4. Update your UI from those read endpoints.

​
Browser caveat

Standard browser EventSource does not let you attach an Authorization header. If your app runs in the browser, use one of these approaches:
  • Proxy the stream through your backend
  • Use a fetch-based streaming client instead of EventSource
  • Open the SSE stream from a native, desktop, or server environment that supports bearer headers

​
Cache behavior

Playback read endpoints return live user state and should be treated as non-cacheable application data.

​
Failure handling

If the SSE connection drops:
  • reconnect with backoff
  • fetch /playback/now-playing after reconnecting
  • do not assume missed SSE messages contain the full state you need
If the stream handshake fails, capture the X-PunchPlay-Request-Id response header when available and log the endpoint, timestamp, and status code.