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
GET /api/public/v1/status

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. Public profile responses may also contain the existing online, donor, donation, subscription, and XP fields shown in the response schema. They are public profile attributes, not authentication signals; display only the fields your feature needs and direct users to PunchPlay’s current profile-visibility and privacy controls for questions about their meaning.

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. Catalog and community responses are bounded by the current public contract. These endpoints do not currently accept page or cursor; do not present a single response as a complete catalog. Use the documented category and type filters, and treat a future pagination field as an additive contract change.

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

GET /api/public/v1/status does not require authentication and reports the public API/database health view. It is suitable for an integration status page, but it is not a substitute for your own network or DNS monitoring.

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