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

# Public API

> Read public PunchPlay profile data without authentication.

The public API is read-only and supports public profiles, catalog discovery, and community overview experiences.

## Endpoints

```text theme={null}
GET /api/public/v1/users/{username}
GET /api/public/v1/catalog/search?q={query}&type={movie|show|anime}
GET /api/public/v1/catalog/trending?type={movie|show|anime}
GET /api/public/v1/catalog/discover?category={popular|now_playing|upcoming|top_rated}&type={movie|show|anime}
GET /api/public/v1/community/overview
```

## What it returns

The response contains:

* public profile basics
* watch stats
* recent watch history

Catalog title cards expose a routable `type` of `movie` or `show`, plus
`category` and `isAnime` classification fields. Anime discovery uses TMDB base
identities; mapped series receive TVDB enrichment and official episode ordering
through authenticated title and playback APIs.

## When to use it

Use the public API for:

* profile widgets
* public dashboards
* bots
* companion overlays that do not need private user authorization
* native search, trending, and discovery screens
* public community dashboards

Do not use it for:

* live playback state
* app-to-user authenticated actions
* writing watches, ratings, or playback updates

## Query parameters

| Parameter      | Description                                      | Default |
| -------------- | ------------------------------------------------ | ------- |
| `historyLimit` | Number of recent watch-history entries to return | `8`     |

Allowed range: `1` to `20`.

## Example request

```bash theme={null}
curl "https://punchplay.tv/api/public/v1/users/scott?historyLimit=5"
```

## Example response

```json theme={null}
{
  "version": "v1",
  "profile": {
    "username": "scott",
    "displayName": "Scott",
    "bio": "Movies, anime, and TV.",
    "avatarUrl": "https://...",
    "isOnline": false,
    "isDonor": false,
    "donationCount": 0,
    "isSubscriber": false,
    "xp": 1200,
    "memberSince": "2026-05-01T10:20:30.000Z"
  },
  "stats": {
    "watched": 184,
    "topGenre": "Drama"
  },
  "recentWatchHistory": []
}
```

## Behavior

* No authentication required
* Only public profiles are returned
* CORS is enabled
* Requests are rate limited per IP

## Error responses

| Status | Meaning                                 |
| ------ | --------------------------------------- |
| `400`  | Invalid username or query parameter     |
| `404`  | User not found or profile is not public |
| `429`  | Rate limit exceeded                     |

## Platform API vs Public API

| Need                           | Use          |
| ------------------------------ | ------------ |
| Live playback writes           | Platform API |
| Authenticated app integrations | Platform API |
| Public read-only profile data  | Public API   |