> ## Documentation Index
> Fetch the complete documentation index at: https://docs.punchplay.tv/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Build secure apps on top of PunchPlay's versioned platform and public APIs.

PunchPlay exposes two API surfaces today:

| Surface      | Best for                                                                                         | Auth                                                      |
| ------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Platform API | Native and third-party apps with account, title, history, library, calendar, and playback access | Bearer token via authorization code + PKCE or device code |
| Public API   | Public profile embeds, dashboards, bots, and companion widgets                                   | No auth                                                   |

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="zap" href="/quickstart">
    Register an app, choose an auth flow, and send your first playback event.
  </Card>

  <Card title="Authentication" icon="shield" href="/authentication">
    Choose between OAuth + PKCE and device code, then implement tokens securely.
  </Card>

  <Card title="Playback API" icon="play" href="/playback-api">
    Send start, pause, resume, stop, and progress events from your integration.
  </Card>

  <Card title="Native App API" icon="smartphone" href="/native-app-api">
    Build the core iOS or Android experience with titles, history, library, calendar, and playback.
  </Card>

  <Card title="Public API" icon="users" href="/public-api">
    No-auth read-only access to public profiles when you do not need user grants.
  </Card>
</CardGroup>

## 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

```text theme={null}
https://punchplay.tv
```

## Need read-only data only?

If you only need public profile data, skip the platform auth flow and use the [Public API](/public-api) instead.