Skip to main content
PunchPlay exposes two API surfaces today:

​
What you can build

  • Second-screen apps that stay in sync with what a user is watching
  • Complete movie and TV companion apps with title details, history, ratings, lists, collection, calendar, and Continue Watching
  • Desktop or TV integrations that report playback lifecycle events
  • Browser apps and websites that connect a PunchPlay account with OAuth
  • Public profile widgets, community dashboards, and analytics overlays

​
Current platform capabilities

  • Developer app registration at https://punchplay.tv/developers
  • Confidential and public client types
  • Per-app allowed_scopes
  • Authorization code + PKCE for web, browser, and native apps with a callback
  • Device code for TV, desktop, CLI, and clients without a convenient callback
  • Versioned platform endpoints under /api/platform/v1
  • Scope-aware platform tokens
  • Title, season, and episode metadata backed by TMDB IDs
  • Watch-history logging, editing, deletion, ratings, favourites, and watch statuses
  • User list and collection management
  • Calendar and Continue Watching reads
  • Playback writes for start, pause, resume, stop, and progress
  • Live playback state via now-playing, in-progress, and SSE updates
  • Request-scoped error IDs for platform debugging
  • Read-only public user data under /api/public/v1
  • Public health status at /api/public/v1/status

​
Start here

Quickstart

Register an app, choose an auth flow, and send your first playback event.

Authentication

Choose between OAuth + PKCE and device code, then implement tokens securely.

Playback API

Send start, pause, resume, stop, and progress events from your integration.

Native App API

Build the core iOS or Android experience with titles, history, library, calendar, and playback.

Public API

No-auth read-only access to public profiles when you do not need user grants.

Data Conventions

Use the right field names, time units, progress scale, IDs, and cursors.

​
Status and versioning

All public developer endpoints are versioned. The current Platform API contract is v1 beta; breaking changes may still be recorded within that beta namespace, so pin and validate the OpenAPI version you integrate. The Public API is stable at v1.
  • Platform endpoints live under /api/platform/v1
  • Stable public endpoints live under /api/public/v1
  • Breaking changes will ship in a new versioned namespace
For a contract or integration question, bring the request ID and UTC timestamp to the PunchPlay Discord. Do not post tokens or client secrets.

​
Base URL

​
Need read-only data only?

If you only need public profile data, skip the platform auth flow and use the Public API instead.