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

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

​
Status and versioning

All public developer endpoints are versioned. The current Platform API contract is v1 beta; 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

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