> ## Documentation Index
> Fetch the complete documentation index at: https://docs.punchplay.tv/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Events

> Read Continue Watching, now-playing state, in-progress items, and server-sent playback updates.

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

```bash theme={null}
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

```bash theme={null}
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.

Dismiss an item with:

```bash theme={null}
curl -X DELETE https://punchplay.tv/api/platform/v1/playback/in-progress/PROGRESS_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Continue Watching

```bash theme={null}
curl https://punchplay.tv/api/platform/v1/me/continue-watching \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

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

```bash theme={null}
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:

```json theme={null}
{
  "emittedAt": "2026-06-08T12:00:00.000Z",
  "sequence": 4,
  "userId": "user_id"
}
```

## Recommended client pattern

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.