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

Every playback request must include deterministic event and session identifiers, a client event timestamp, and enough media identity to resolve the title.

{
  "event_id": "evt_123",
  "event_created_at": 1780910400000,
  "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	Required unique identifier for idempotent event processing
`media_type`	`movie` or `episode`	Required
`title`	string	Required
`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	Required for episode playback; specials use season `0`
`episode`	number	Required for episode playback
`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	Completion ratio between `0` and `1`; never send a percentage such as `20`
`duration_seconds`	number	Total runtime; required when `progress` supplies the resume position
`position_seconds`	number	Authoritative resume position; required for `pause`, `progress`, and incomplete `stop` unless `progress` and `duration_seconds` are supplied
`device_id`	string	Client or device identity
`playback_session_id`	string	Required stable identifier for ordering and session lifecycle
`event_created_at`	number	Required Unix timestamp in milliseconds; cannot be more than five minutes in the future
`client_version`	string	Integration version for diagnostics
`watched`	boolean	Explicit watch completion override on stop
`watched_threshold`	number	Completion threshold greater than `0` and at most `1`
`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.
A newer incomplete stop can update an existing passive snapshot when it uses the same playback_session_id, a new event_id, and a later event_created_at.
Newer progress after a stopped session can reopen the session.
pause updates an active session without creating a watch. A standalone pause returns 409 playback_state_conflict.

Passive resume sync

When importing an existing resume position from another tracker or media server, send one incomplete stop. No preceding start, progress, or pause request is required. PunchPlay stores the item as inactive resumable progress, so it appears in Continue Watching without appearing as now playing.

curl -X POST https://punchplay.tv/api/platform/v1/playback/stop \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id":"crosswatch-resume:movie:550:1800",
    "media_type":"movie",
    "title":"Fight Club",
    "tmdb_id":550,
    "position_seconds":1800,
    "duration_seconds":8340,
    "watched":false,
    "playback_session_id":"crosswatch:movie:550",
    "event_created_at":1780910400000
  }'

Do not send progress followed by pause for a passive import. progress represents active playback and may briefly publish a now-playing state. A standalone pause is a transition for an existing live session and is rejected. To refresh a passive resume position, reuse the stable playback_session_id, generate a new event_id, and send a later event_created_at. PunchPlay compares provider event time rather than arrival time, so delayed older snapshots cannot overwrite newer progress.

Best practices

Always send a stable playback_session_id.
Generate a unique event_id for each logical playback update and reuse it only when retrying that same event.
Send the original client event time in event_created_at, not the retry time.
Send tmdb_id whenever available.
Include position_seconds and duration_seconds for accurate progress.
Keep progress in the 0 to 1 range. PunchPlay can derive position_seconds from progress only when duration_seconds is present.

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.

Status	Error	Meaning
`400`	`invalid_request`	Required fields are missing, malformed, unsupported, or outside their allowed range
`409`	`playback_state_conflict`	The action requires lifecycle state that does not exist, such as a standalone pause
`422`	`media_not_found`	PunchPlay could not resolve the supplied media identity
`500`	`server_error`	Playback processing failed unexpectedly; retry with backoff and retain the request ID

Getting Started

Guides

Reference

Supported actions

Minimum payload shape

Supported payload fields

Movie example

Episode example

Event ordering behavior

Passive resume sync

Best practices

Completion rules

Failure handling

​Supported actions

​Minimum payload shape

​Supported payload fields

​Movie example

​Episode example

​Event ordering behavior

​Passive resume sync

​Best practices

​Completion rules

​Failure handling

Supported actions

Minimum payload shape

Supported payload fields

Movie example

Episode example

Event ordering behavior

Passive resume sync

Best practices

Completion rules

Failure handling