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/playback/events requires events:read

​
Now Playing

curl https://punchplay.tv/api/platform/v1/playback/now-playing \
  -H "Authorization: Bearer ACCESS_TOKEN"
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

curl https://punchplay.tv/api/platform/v1/playback/in-progress \
  -H "Authorization: Bearer ACCESS_TOKEN"
Use this when you need a queue of active or resumable items rather than a single now-playing object.

​
Server-sent events

curl https://punchplay.tv/api/platform/v1/playback/events \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: text/event-stream"
The stream sends lightweight notifications whenever playback state changes. Event types:
  • ready
  • playback-update
playback-update includes: 
{
  "emittedAt": "2026-06-08T12:00:00.000Z",
  "sequence": 4,
  "userId": "user_id"
}
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.