Playback API

The playback API is the core of the PunchPlay platform. It accepts playback lifecycle events and turns them into now-playing state, in-progress items, playback sessions, and watch history. This surface requires the playback:write scope. A stop that resolves as watched and creates history also requires history:write.

Supported actions

Send these actions to:

POST /api/platform/v1/playback/{action}

Available actions:

start
pause
resume
stop
progress

Minimum payload shape

At a minimum, send enough identity to resolve the title reliably.

{
  "media_type": "movie",
  "title": "Fight Club",
  "year": 1999,
  "tmdb_id": 550,
  "playback_session_id": "player-session-123"
}

Supported payload fields

Field	Type	Notes
`event_id`	string	Stable event identifier for dedupe
`media_type`	`movie` or `episode`	Required
`title`	string	Required in practice for reliable identification
`year`	number	Helpful for movie disambiguation
`imdb_id`	string	Optional external identifier
`tmdb_id`	number	Preferred metadata identifier
`tvdb_id`	number	TVDB identifier used for mapped anime-series enrichment
`punchplay_id`	string	PunchPlay-native identifier when available
`season`	number	Episode season number
`episode`	number	Episode number
`episode_end`	number	End episode for multi-episode playback
`absolute_episode`	number	Absolute numbering resolved against TVDB anime episode ordering
`episode_title`	string	Optional episode title
`multi_episode`	boolean	Indicates multi-episode playback
`anime`	boolean	Classifies playback as anime without changing `media_type`
`progress`	number	Fractional progress between `0` and `1`
`duration_seconds`	number	Total runtime
`position_seconds`	number	Current playback position
`device_id`	string	Client or device identity
`playback_session_id`	string	Critical for ordering and session lifecycle
`event_created_at`	number	Millisecond timestamp from the client
`client_version`	string	Integration version for diagnostics
`watched`	boolean	Explicit watch completion override on stop
`watched_threshold`	number	Completion threshold when using progress-derived stops
`raw_filename`	string	Helps fallback matching

Movie example

curl -X POST https://punchplay.tv/api/platform/v1/playback/progress \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_123",
    "media_type": "movie",
    "title": "Fight Club",
    "year": 1999,
    "tmdb_id": 550,
    "position_seconds": 1800,
    "duration_seconds": 8340,
    "progress": 0.2158,
    "device_id": "living-room-mac",
    "playback_session_id": "player-session-123",
    "event_created_at": 1780910400000
  }'

Episode example

curl -X POST https://punchplay.tv/api/platform/v1/playback/stop \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_456",
    "media_type": "episode",
    "title": "Severance",
    "tmdb_id": 95396,
    "season": 1,
    "episode": 2,
    "episode_title": "Half Loop",
    "position_seconds": 3000,
    "duration_seconds": 3200,
    "watched_threshold": 0.9,
    "playback_session_id": "session-episode-456",
    "event_created_at": 1780910460000
  }'

Event ordering behavior

PunchPlay applies session-aware event handling so clients can send real playback events without manually reconstructing user state. Important behaviors:

Duplicate event_id values are deduped.
A stop may create a completed watch or only save progress, depending on completion state.
Older events that arrive after a stop are ignored.
Newer progress after a stopped session can reopen the session.
pause updates state without creating a watch.

Best practices

Always send a stable playback_session_id.
Send event_created_at from the client, not the server, when possible.
Send tmdb_id whenever available.
Include position_seconds and duration_seconds for accurate progress.
Treat event_id as required if your client can generate one.

Completion rules

A stop event is treated as watched when one of these is true:

watched is explicitly true
progress or derived progress meets watched_threshold

If a stop does not qualify as watched, PunchPlay stores progress instead of creating a completed watch entry. When a stop does qualify as watched, the token must include history:write. Request that scope during authorization for clients that are allowed to create completed watch history.

Failure handling

Platform playback errors include:

request_id in the JSON body
X-PunchPlay-Request-Id in the response headers

Capture that value when reporting failed writes or invalid payloads.

Getting Started

Guides

Reference

Supported actions

Minimum payload shape

Supported payload fields

Movie example

Episode example

Event ordering behavior

Best practices

Completion rules

Failure handling

​Supported actions

​Minimum payload shape

​Supported payload fields

​Movie example

​Episode example

​Event ordering behavior

​Best practices

​Completion rules

​Failure handling

Supported actions

Minimum payload shape

Supported payload fields

Movie example

Episode example

Event ordering behavior

Best practices

Completion rules

Failure handling