Quickstart

This guide walks through the smallest useful integration:

Create a developer app and get your credentials
Choose the right auth flow and scopes for your app
Get an access token and verify the identity
Send a complete playback lifecycle
Read playback state
Refresh the access token when needed

Choose scopes for the job

Request only what the integration needs. These recipes assume the app is registered with the listed scopes in allowed_scopes:

Integration	Scopes
Public profile or catalog widget	No Platform token; use the Public API
Playback tracking without completed watches	`profile:read playback:read playback:write` (add `events:read` for SSE)
Playback tracking that can complete and verify watches	`profile:read playback:read playback:write history:read history:write` (add `events:read` for SSE)
Library synchronization	`profile:read history:read history:write ratings:read ratings:write lists:read lists:write collection:read collection:write playback:read`; omit resource groups you do not mirror

playback:write lets an app send lifecycle events. A stop that resolves as a completed watch also needs history:write; ask for that scope before the user authorizes the app rather than discovering the requirement after playback has started.

Before you begin

You need:

A PunchPlay account
A developer app from Get API key
Your app’s client_id
Your app’s client_secret if you created a confidential client

1. Create a developer app

A confidential client for server-backed apps that can safely store a secret
A public client for native or browser-based apps that must not embed a secret

Also:

register your redirect URIs if you plan to use OAuth
choose the minimum allowed_scopes your app should ever request
save the secret immediately if you created a confidential client

2. Choose your auth flow

Use:

authorization code + PKCE for browser, website, and native apps that can receive a callback
device code for TV, desktop, CLI, and clients without a convenient browser callback

3A. Apps with callbacks: authorization code + PKCE

Redirect the user to:

https://punchplay.tv/api/platform/v1/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fpunchplay%2Fcallback&code_challenge=YOUR_PKCE_CHALLENGE&code_challenge_method=S256&scope=profile%3Aread%20playback%3Aread%20playback%3Awrite%20history%3Aread%20history%3Awrite&state=YOUR_STATE

After PunchPlay redirects back with code, exchange it for tokens:

curl -X POST https://punchplay.tv/api/platform/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://example.com/auth/punchplay/callback" \
  -d "code_verifier=YOUR_ORIGINAL_PKCE_VERIFIER"

Third-party clients use this redirect-based flow to let PunchPlay’s signed-in consent UI collect the decision. Do not call the internal consent-submission POST yourself; the API reference labels it for PunchPlay’s own same-origin UI.

3B. Apps without callbacks: device code

Request a device code:

curl -X POST https://punchplay.tv/api/platform/v1/auth/device/code \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "profile:read playback:read playback:write history:read history:write events:read"
  }'

Public clients send client_id only. Confidential clients send both client_id and client_secret. The example requests the scopes needed for a complete playback lifecycle, including a completed-watch stop. A read-only widget or a tracker that never creates completed history can use the smaller recipes above. A full native client normally requests the scope set documented in the Native App API. Example response:

{
  "user_code": "ABCD-1234",
  "device_code": "raw_device_code",
  "verification_uri": "https://punchplay.tv/link",
  "verification_uri_complete": "https://punchplay.tv/link?code=ABCD-1234&type=platform",
  "verification_uri_qr": "data:image/png;base64,...",
  "expires_in": 600,
  "scope": "profile:read playback:read playback:write history:read history:write events:read"
}

Display the user_code or open verification_uri_complete for the user, then poll:

curl -X POST https://punchplay.tv/api/platform/v1/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "device_code": "raw_device_code",
    "device_name": "PunchPlay Companion"
  }'

While approval is pending, the API returns:

{ "error": "authorization_pending", "message": "Device code has not been approved yet.", "request_id": "ppreq_..." }

Once approved, both auth flows produce bearer credentials shaped like this:

{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_expires_in": 31536000,
  "scope": "profile:read playback:read playback:write history:read history:write events:read"
}

4. Check the authenticated identity

Before writing playback, verify that the token belongs to the account the user just authorized and that the expected scopes were granted:

curl https://punchplay.tv/api/platform/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

The response includes the stable user ID and the granted scopes array. Stop and re-authorize if the required scope is missing.

5. Send a complete playback lifecycle

The following shell variables create fresh UUIDs and timestamps for one walkthrough. Reuse an event_id only when retrying that same logical event; generate a new one for each later event. event_created_at is Unix time in milliseconds and must describe when the client event occurred.

SESSION_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
START_EVENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
STARTED_AT_MS="$(node -p 'Date.now()')"

Start the movie:

curl -X POST https://punchplay.tv/api/platform/v1/playback/start \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "'"$START_EVENT_ID"'",
    "event_created_at": '"$STARTED_AT_MS"',
    "media_type": "movie",
    "title": "Fight Club",
    "year": 1999,
    "tmdb_id": 550,
    "position_seconds": 0,
    "duration_seconds": 8340,
    "playback_session_id": "'"$SESSION_ID"'",
    "device_id": "macbook-air-living-room"
  }'

Send progress while the user is watching:

PROGRESS_EVENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
PROGRESS_AT_MS="$(node -p 'Date.now()')"

curl -X POST https://punchplay.tv/api/platform/v1/playback/progress \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "'"$PROGRESS_EVENT_ID"'",
    "event_created_at": '"$PROGRESS_AT_MS"',
    "media_type": "movie",
    "title": "Fight Club",
    "year": 1999,
    "tmdb_id": 550,
    "position_seconds": 3600,
    "duration_seconds": 8340,
    "progress": 0.4317,
    "playback_session_id": "'"$SESSION_ID"'",
    "device_id": "macbook-air-living-room"
  }'

While the session is active, read the materialized now-playing state:

curl https://punchplay.tv/api/platform/v1/playback/now-playing \
  -H "Authorization: Bearer ACCESS_TOKEN"

An active response includes fields like these:

{
  "type": "movie",
  "tmdbId": 550,
  "title": "Fight Club",
  "year": 1999,
  "progressPercent": 43.17,
  "progressSeconds": 3600,
  "durationSeconds": 8340,
  "updatedAt": "2026-09-05T06:41:00.000Z",
  "nowPlaying": true,
  "playbackState": "watching",
  "mediaSource": "tmdb"
}

When the user reaches the end, send a fresh stop event. With history:write, this creates the completed watch record:

STOP_EVENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
STOP_AT_MS="$(node -p 'Date.now()')"

curl -X POST https://punchplay.tv/api/platform/v1/playback/stop \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "'"$STOP_EVENT_ID"'",
    "event_created_at": '"$STOP_AT_MS"',
    "media_type": "movie",
    "title": "Fight Club",
    "year": 1999,
    "tmdb_id": 550,
    "position_seconds": 8340,
    "duration_seconds": 8340,
    "watched": true,
    "playback_session_id": "'"$SESSION_ID"'",
    "device_id": "macbook-air-living-room"
  }'

Expected response:

{
  "ok": true,
  "media_type": "movie",
  "tmdb_id": 550,
  "tvdb_id": null,
  "imdb_id": "tt0137523",
  "punchplay_id": "tmdb:movie:550"
}

6. Confirm the post-stop state

After a completed stop, the item is no longer active. Read the resumable queue to confirm that no incomplete progress remains for this session:

curl https://punchplay.tv/api/platform/v1/playback/in-progress \
  -H "Authorization: Bearer ACCESS_TOKEN"

If you query playback/now-playing after the completed stop, the response may contain no active item. Use GET /api/platform/v1/me/history with history:read when you need to verify the completed watch record.

7. Refresh the access token when needed

Web and browser apps can refresh through the OAuth token endpoint:

curl -X POST https://punchplay.tv/api/platform/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=REFRESH_TOKEN"

Successful refresh returns a rotated refresh token. Replace the old one immediately.

{
  "access_token": "new_access_token",
  "refresh_token": "new_refresh_token",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_expires_in": 31415926,
  "scope": "profile:read playback:read playback:write history:read history:write"
}

Device-code clients can refresh here:

curl -X POST https://punchplay.tv/api/platform/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "refresh_token":"REFRESH_TOKEN"
  }'

Successful refresh returns a rotated refresh token. Replace the old one immediately.

{
  "access_token": "new_access_token",
  "refresh_token": "new_refresh_token",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_expires_in": 31415926,
  "scope": "profile:read playback:read playback:write history:read history:write events:read"
}

Common errors

authorization_pending: the user has not approved the device code yet
invalid_scope: the request asked for a scope outside the app policy
invalid_client: the provided app credentials are wrong
insufficient_scope: the token cannot access the endpoint you called
429: you are polling or sending events too aggressively

Platform failures include request_id in the body and X-PunchPlay-Request-Id in the headers. Log that value so you can send it to support.

Test safely

The current developer API does not provide a separate sandbox host. Create one PunchPlay account and one developer app dedicated to integration testing. Keep their tokens outside source control, use a known real fixture such as Fight Club (tmdb_id: 550) rather than inventing catalogue data, and clean up reversible list, collection, preference, and dismissed-progress writes in a finally path. A completed history write can award XP and playback can leave session/audit records, so run the full start-to-stop example only on that isolated account. For help, bring the UTC timestamp, endpoint, status, response body, and request ID to PunchPlay Discord.

Next steps

Read Authentication for both auth flows, token lifecycle, and security guidance.
Read Native App API for title, history, ratings, lists, collection, calendar, and Continue Watching endpoints.
Read Playback API for payload design, event ordering, and multi-episode behavior.
Read Live Events to subscribe to playback changes in real time.

Getting Started

Guides

Reference

Choose scopes for the job

Before you begin

1. Create a developer app

2. Choose your auth flow

3A. Apps with callbacks: authorization code + PKCE

3B. Apps without callbacks: device code

4. Check the authenticated identity

5. Send a complete playback lifecycle

6. Confirm the post-stop state

7. Refresh the access token when needed

Common errors

Test safely

Next steps

​Choose scopes for the job

​Before you begin

​1. Create a developer app

​2. Choose your auth flow

​3A. Apps with callbacks: authorization code + PKCE

​3B. Apps without callbacks: device code

​4. Check the authenticated identity

​5. Send a complete playback lifecycle

​6. Confirm the post-stop state

​7. Refresh the access token when needed

​Common errors

​Test safely

​Next steps

Choose scopes for the job

Before you begin

1. Create a developer app

2. Choose your auth flow

3A. Apps with callbacks: authorization code + PKCE

3B. Apps without callbacks: device code

4. Check the authenticated identity

5. Send a complete playback lifecycle

6. Confirm the post-stop state

7. Refresh the access token when needed

Common errors

Test safely

Next steps