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

/me/continue-watching returns show-level summaries: the show’s current season/episode and completion state. It is useful for a “next episode” row, but it is not the source of an exact movie or episode resume position. Fetch /api/platform/v1/me/continue-watching/{showId} when you need the details for a show. Use /api/platform/v1/playback/in-progress for resumable movie or episode items with progressSeconds, durationSeconds, and the progress identifier used by the dismiss endpoint.

​
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.
An SSE connection is authorized when it is opened. Access tokens expire after one hour and revocation can make an existing credential unusable, so track the token expiry, close the stream before it expires, refresh the token, and reconnect. If a connection drops or a refresh/revocation race produces a 401, refresh or re-authorize before reconnecting. Do not treat an open stream as a permanent authorization grant.

​
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 or its handshake returns 503 service_unavailable, wait for the Retry-After delay when one is present (otherwise use bounded exponential backoff) before reconnecting:
  • fetch /playback/now-playing after reconnecting
  • do not assume missed SSE messages contain the full state you need
SSE notifications are lightweight invalidations, not a durable delivery queue. Use the change feed in Partner Sync when a mirror must recover every change, and reconcile with a read endpoint after reconnecting. If your deployment has multiple application processes, verify the event fan-out topology; a process-local listener cannot by itself guarantee cross-process delivery. If the stream handshake fails, capture the X-PunchPlay-Request-Id response header when available and log the endpoint, timestamp, and status code.