Skip to main content
The public API is read-only and intended for public profile experiences.

​
Endpoint

GET /api/public/v1/users/{username}

​
What it returns

The response contains:
  • public profile basics
  • watch stats
  • recent watch history

​
When to use it

Use the public API for:
  • profile widgets
  • public dashboards
  • bots
  • companion overlays that do not need private user authorization
Do not use it for:
  • live playback state
  • app-to-user authenticated actions
  • writing watches, ratings, or playback updates

​
Query parameters

ParameterDescriptionDefault
historyLimitNumber of recent watch-history entries to return8
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

StatusMeaning
400Invalid username or query parameter
404User not found or profile is not public
429Rate limit exceeded

​
Platform API vs Public API

NeedUse
Live playback writesPlatform API
Authenticated app integrationsPlatform API
Public read-only profile dataPublic API