Skip to main content
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.

​
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

FieldTypeNotes
event_idstringStable event identifier for dedupe
media_typemovie or episodeRequired
titlestringRequired in practice for reliable identification
yearnumberHelpful for movie disambiguation
imdb_idstringOptional external identifier
tmdb_idnumberPreferred metadata identifier
tvdb_idnumberOptional external identifier
punchplay_idstringPunchPlay-native identifier when available
seasonnumberEpisode season number
episodenumberEpisode number
episode_endnumberEnd episode for multi-episode playback
absolute_episodenumberAbsolute numbering for anime-like episode data
episode_titlestringOptional episode title
multi_episodebooleanIndicates multi-episode playback
animebooleanHelps anime resolution
progressnumberFractional progress between 0 and 1
duration_secondsnumberTotal runtime
position_secondsnumberCurrent playback position
device_idstringClient or device identity
playback_session_idstringCritical for ordering and session lifecycle
event_created_atnumberMillisecond timestamp from the client
client_versionstringIntegration version for diagnostics
watchedbooleanExplicit watch completion override on stop
watched_thresholdnumberCompletion threshold when using progress-derived stops
raw_filenamestringHelps 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.

​
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.