Public API

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

Endpoints

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

curl "https://punchplay.tv/api/public/v1/users/scott?historyLimit=5"

Example response

{
  "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

Getting Started

Guides

Reference

Endpoints

What it returns

When to use it

Query parameters

Example request

Example response

Behavior

Error responses

Platform API vs Public API

​Endpoints

​What it returns

​When to use it

​Query parameters

​Example request

​Example response

​Behavior

​Error responses

​Platform API vs Public API

Endpoints

What it returns

When to use it

Query parameters

Example request

Example response

Behavior

Error responses

Platform API vs Public API