PlayHub documentation

API v1 reference

Integrate mobile, TV, and companion clients with the versioned PlayHub backend contract. Browse every endpoint or download the full schema.

OpenAPI 3.1191 paths · 230 operationsUpdated 10 October 2026

01Start integration 02Authentication 03Playback 04Download OpenAPI

Integration basics

The native API contract

Use your installed site’s canonical HTTPS origin followed by /api/v1. The versionless /api remains the website contract and rejects native tokens. OpenAPI contract metadata 1.0.0, web release 0.9.13, and native app versions are independent.

Download the complete OpenAPI 3.1 YAML for request bodies, response schemas, validation constraints, and operation-specific rate limits. This reference contains all 191 paths and 230 operations from the supplied contract. Capability discovery and authorization determine which are enabled on a particular installation.

First request · replace origin and installed version

GET /api/v1/bootstrap HTTP/1.1
Host: video.example.com
Accept: application/json
X-PlayHub-Client: android
X-PlayHub-App-Version: 1.0.0
X-PlayHub-Device-Id: android.install.example01
X-PlayHub-Locale: en-US
X-PlayHub-Timezone: UTC

Requests

Headers, bootstrap, and capabilities

Header	Meaning
Accept	`application/json`
Authorization	`Bearer <native access token>` on protected calls; optional on public catalog calls.
X-PlayHub-Client	Exactly `ios`, `android`, `android-tv`, `tvos`, `tizen`, or `webos`.
X-PlayHub-App-Version	The actual installed client version.
X-PlayHub-OS-Version / Device-Model	OS/runtime and user-recognizable device model.
X-PlayHub-Device-Id	Stable installation identifier, 8–128 safe characters; use an installation ID, never an advertising ID.
X-PlayHub-Locale / Timezone	BCP 47-like locale and IANA timezone.
X-PlayHub-Capabilities	JSON document up to 4096 bytes for codecs, containers, resolution, subtitles, and features. Playback response remains authoritative.
X-Request-ID	Optional UUID, fresh per logical request and retained across transport retries. Responses echo/generate request ID.

Bootstrap is privately cacheable for 60 seconds and varies by client headers. Refresh at cold start, after login/version changes, and after foregrounding when stale. Honor maintenance, supported/minimum versions, required/available updates and update URLs, authentication policy, legal/support URLs, and each feature flag.

TV clients do not receive mobile account mutation/upload/creator/Live publishing abilities. Native messaging exists in the current contract; older readiness prose saying it is absent is superseded. Native purchase processing remains unavailable. FCM/APNs source delivery exists but defaults off and requires credentials, tables, a push worker, and actual device acceptance. Feature flags never replace endpoint authorization.

Identity and devices

Authentication, refresh, and TV pairing

Mobile login accepts iOS/Android with device context; headers take precedence over body context. Registration follows bootstrap policy, availability, CAPTCHA, email/phone verification and confirmation. Login CAPTCHA challenges are single-use; fetch a new challenge after each attempted verification.

Store the returned access/refresh pair in OS secure storage. Access defaults to 30 days; refresh defaults to a 180-day sliding lifetime. Serialize refresh calls per installation and atomically replace both credentials. Refresh preserves the session ID while revoking the old access token and consuming the previous refresh credential. Reuse revokes the credential family, device session and matching push registration. Platform/device mismatch is rejected without consumption; expired/revoked/restricted accounts require sign-in.

Sessions support inventory, rename, and revocation. Reauthentication on one installation replaces its previous session. The default session ceiling is ten, bounded by deployment policy. Social login uses exact allowlisted return URIs, PKCE S256 and a single-use handoff exchanged through the native API; default callback playhub://auth/callback.

TV pairing displays a user code/verification URI and keeps the device code private. The signed-in companion approves the device; TV polling honors the returned interval, authorization_pending, slow_down, denial/expiry and Retry-After. Approval is consumed once and issues a restricted TV token.

Error handling

Responses, pagination, and retry

Success envelope

{"data": {"message": "Request completed."}, "meta": {"request_id": "…"}}

Validation error envelope

{"error": {"code": "validation_failed", "message": "The submitted data is invalid.", "status": 422, "request_id": "…", "validation": {"email": ["Enter a valid email."]}}}

Length-aware pagination uses meta.pagination with page/per_page/total/last_page/has_more. Cursor pagination uses next_cursor/previous_cursor/per_page/has_more; normalized links appear under meta.links. Non-204 JSON success responses use the data/meta envelope.

Status	Client response
401	Refresh or sign in.
403	Check account ability and resource access.
404	Resource absent or intentionally hidden.
406	Choose compatible playback capabilities.
409	Reconcile current state before retry.
422	Show field validation.
429	Respect Retry-After and back off.
503	Dependency unavailable; bounded delayed retry where appropriate.

Branch on stable error.code and retain request IDs; do not expose credentials or traces. Unless an operation is stricter, the shared limit is 240 requests/minute per authenticated user/source IP. Use bounded exponential backoff with jitter for retryable idempotent reads and PUTs; do not blindly replay financial, validation, forbidden, or missing-resource operations. Responses include X-Request-ID, X-PlayHub-API-Version: 1, and X-Content-Type-Options: nosniff.

Playback and publishing

Media, uploads, Live, and push

Obtain a playback session and use its returned sources, subtitles, chapters, expiration/access data, and capability result. Refresh expired signed URLs rather than inventing storage paths. Receiver handoff reauthorizes access and requires explicitly allowlisted public HTTPS origins; bearer credentials must not reach receivers. iOS chooses MP4/HLS; DASH-only items need a compatible server source.

Resumable uploads are server-proxied chunks with resumable session status/finalization and asynchronous processing; direct-to-cloud multipart transport is false. Progress writes are idempotent. Watch history and library honor current ownership/access rules.

Live viewer/publisher tokens and resource permissions are distinct from HTTP authentication. Current server admission, queue/scheduler, TURN, egress and replay setup is explained in the Live server guide. Push registration stores platform/environment/device context, never returns the raw token, and must be paired with operational FCM/APNs delivery. See the push configuration guide.

Endpoint reference

Bootstrap

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/bootstrap`	Public	Bootstrap a client Returns branding, feature flags, authentication methods, version enforcement, playback capabilities, and service links. Cacheable privately for 60 seconds and varied by client headers. Parameters: `X-PlayHub-Client`, `X-PlayHub-App-Version`, `X-PlayHub-OS-Version`, `X-PlayHub-Device-Model`, `X-PlayHub-Locale`, `X-PlayHub-Timezone`, `X-PlayHub-Capabilities`. Responses: 200, 429, default.

GET

/bootstrap

Public

Bootstrap a client

Returns branding, feature flags, authentication methods, version enforcement, playback capabilities, and service links. Cacheable privately for 60 seconds and varied by client headers.

Parameters: X-PlayHub-Client, X-PlayHub-App-Version, X-PlayHub-OS-Version, X-PlayHub-Device-Model, X-PlayHub-Locale, X-PlayHub-Timezone, X-PlayHub-Capabilities.

Responses: 200, 429, default.

Endpoint reference

Authentication

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/auth/login-captcha`	Public	Get a native login captcha challenge Call after login returns captcha_required. Available independently of the registration captcha policy. Render the returned data-URI image and submit id as captcha_id plus the entered captcha_answer with the next login request. A challenge is consumed after one verification attempt; fetch a new challenge before retrying. No bearer token or browser cookie is required. Limited to 10/minute and 60/hour per IP. Responses: 200, 429, default.
`GET`	`/auth/registration-captcha`	Public	Get the current registration captcha Responses: 200, default.
`GET`	`/auth/registration-captcha/google`	Public	Open the configured website Google CAPTCHA in the system authentication browser No session or login credential is created. Only exact native callback destinations are allowed. The web response is handed back using S256 PKCE; registration still validates it with Google. Parameters: `return_to` (required), `code_challenge` (required). Responses: 200, default.
`POST`	`/auth/registration-captcha/google/complete`	Public	Return a one-time CAPTCHA handoff code to the exact native callback Request: `application/x-www-form-urlencoded`: `state`, `google_captcha_token`. Responses: 302, default.
`POST`	`/auth/registration-captcha/google/exchange`	Public	Exchange a one-time handoff with its S256 verifier Request: `application/json`: `code`, `code_verifier`. Responses: 200, default.
`GET`	`/auth/registration-availability`	Public	Check username, email, or phone availability Parameters: `username`, `email`, `phone`. Responses: 200, default.
`POST`	`/auth/registration-email-challenge`	Public	Send an email registration verification code Limited to 4/minute and 15/hour per IP, in addition to the global limit. Request: `application/json`: `email`. Responses: 200, 422, 429, default.
`POST`	`/auth/registration-phone-challenge`	Public	Send a phone registration verification code Limited to 4/minute and 15/hour per IP, in addition to the global limit. Request: `application/json`: `phone`, `phone_country_code`, `phone_country_iso`. Responses: 200, 422, 429, default.
`POST`	`/auth/login`	Public	Sign in an iOS or Android device Issues a 30-day bearer token and a rotating, device-bound refresh credential. Both plaintext credentials are returned only in this response. Limited to 8/minute and 40/hour per IP plus normalized login identifier. Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`, `X-PlayHub-App-Version`. Request: `application/json` (see OpenAPI schema). Responses: 200, 401, 422, 429, default.
`POST`	`/auth/refresh`	Public	Silently renew a native mobile or TV session The refresh credential is bound to the original platform and device ID. A successful request rotates both access and refresh credentials while preserving the device-session ID. Reuse of an already-consumed refresh credential revokes the whole device session. The default access lifetime is 30 days and the sliding refresh lifetime is 180 days. Limited to 15/minute and 120/hour per IP/device key. Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`, `X-PlayHub-App-Version`. Request: `application/json`: `refresh_token`, `platform`, `device_id`, `device_name`, `app_version`, `os_version`. Responses: 200, 401, 403, 422, 429, default.
`POST`	`/auth/register`	Public	Register an iOS or Android device user Registration requirements and verification method are discovered through bootstrap. The token is returned only when registration completes immediately. Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`, `X-PlayHub-App-Version`. Request: `application/json` (see OpenAPI schema). Responses: 201, 422, 429, default.
`POST`	`/auth/confirm-registration`	Public	Confirm registration and issue a native token Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`. Request: `application/json` (see OpenAPI schema). Responses: 200, 422, default.
`GET`	`/auth/social/{provider}/redirect`	Public	Begin an OAuth social login handoff Redirects to the configured provider. `return_to` must exactly match the server allowlist and the code challenge uses PKCE S256. This response is a redirect rather than the JSON envelope. Parameters: `provider` (required), `intent`, `return_to` (required), `code_challenge` (required). Responses: 302, 422, 429, default.
`POST`	`/auth/social/exchange`	Public	Exchange a one-time social handoff code The 48-character handoff code is single-use and bound to the PKCE verifier and allowed return URI flow. Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`. Request: `application/json` (see OpenAPI schema). Responses: 200, 401, 422, default.
`POST`	`/auth/forgot-password`	Public	Request password recovery Uses a generic response to reduce account enumeration. Limited to 5/minute per IP. Request: `application/json`: `email`, `phone`, `phone_country_code`, `phone_country_iso`. Responses: 200, 422, 429, default.
`POST`	`/auth/reset-password`	Public	Reset a password using a recovery code Request: `application/json`: `email`, `phone`, `token`, `password`, `password_confirmation`. Responses: 200, 422, 429, default.
`GET`	`/auth/me`	Native bearer required	Get the authenticated user Responses: 200, 401, default.

Endpoint reference

TV pairing

Method	Path (under /api/v1)	Authentication	Contract
`POST`	`/auth/tv/device-authorizations`	Public	Start TV device authorization Returns a secret device code to poll, a short user code, verification URI, expiry, and minimum polling interval. Limited to 10/minute per IP. Parameters: `X-PlayHub-Client`, `X-PlayHub-Device-Id`. Request: `application/json`: `platform`, `device_id`, `device_name`, `app_version`, `os_version`. Responses: 201, 422, 429, default.
`POST`	`/auth/tv/device-authorizations/token`	Public	Poll a TV device authorization Poll no faster than the returned interval. Pending, slow-down, rejected, expired, consumed, and invalid states use stable error codes. An approved code is consumed once and returns a TV-scoped bearer token. Limited to 60/minute per source/device key. Request: `application/json`: `device_code`. Responses: 200, 400, 409, 410, 429, default.
`POST`	`/auth/tv/device-authorizations/preview`	Native bearer required	Preview a TV waiting for approval Request: `application/json`: `user_code`. Responses: 200, 401, 404, default.
`POST`	`/auth/tv/device-authorizations/approve`	Native bearer required	Approve a TV using its user code Request: `application/json`: `user_code`. Responses: 200, 401, 404, 409, default.

Endpoint reference

Sessions

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/auth/sessions`	Native bearer required	List active native device sessions Responses: 200, 401, default.
`DELETE`	`/auth/sessions/current`	Native bearer required	Sign out the current device Responses: 200, 404, default.
`DELETE`	`/auth/sessions/others`	Native bearer required	Sign out every other native device Responses: 200, default.
`DELETE`	`/auth/sessions/all`	Native bearer required	Sign out every native device including the caller Responses: 200, default.
`PATCH`	`/auth/sessions/{deviceSession}`	Native bearer required	Rename an owned device session Parameters: `deviceSession` (required). Request: `application/json`: `device_name`. Responses: 200, 404, 422, default.
`DELETE`	`/auth/sessions/{deviceSession}`	Native bearer required	Sign out an owned device session Parameters: `deviceSession` (required). Responses: 200, 404, default.

Endpoint reference

Admin versions

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/admin/client-versions`	Native bearer required	List version policies for every platform Responses: 200, 401, 403, default.
`PUT`	`/admin/client-versions/{platformAppVersion}`	Native bearer required	Replace one platform version policy Parameters: `platformAppVersion` (required). Request: `application/json`: `latest_version`, `minimum_version`, `supported`, `update_url`, `release_notes_url`, `update_message`. Responses: 200, 403, 422, default.

GET

/admin/client-versions

Native bearer required

List version policies for every platform

Responses: 200, 401, 403, default.

PUT

/admin/client-versions/{platformAppVersion}

Native bearer required

Replace one platform version policy

Parameters: platformAppVersion (required).

Request: application/json: latest_version, minimum_version, supported, update_url, release_notes_url, update_message.

Responses: 200, 403, 422, default.

Endpoint reference

Home

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/home`	Optional bearer	Get the device-aware home feed Returns recommended, trending, latest, Shorts, and live rows. Authenticated users can also receive continue-watching and subscription rows. Parameters: `row_limit`. Responses: 200, 429, default.
`GET`	`/home/sections/{section}`	Optional bearer	Page through one home section The `continue-watching` and `subscriptions` sections require authentication. Parameters: `section` (required), `page`, `per_page`, `cursor`. Responses: 200, 401, 404, default.

GET

/home

Optional bearer

Get the device-aware home feed

Returns recommended, trending, latest, Shorts, and live rows. Authenticated users can also receive continue-watching and subscription rows.

Parameters: row_limit.

Responses: 200, 429, default.

GET

/home/sections/{section}

Optional bearer

Page through one home section

The continue-watching and subscriptions sections require authentication.

Parameters: section (required), page, per_page, cursor.

Responses: 200, 401, 404, default.

Endpoint reference

Catalogue

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/catalog/categories`	Optional bearer	List video categories and public video counts Responses: 200, default.
`GET`	`/catalog/languages`	Optional bearer	List video languages and public video counts Responses: 200, default.

Endpoint reference

Videos

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/videos`	Optional bearer	Discover public videos Parameters: `q`, `channel`, `category`, `type`, `sort`, `page`, `per_page`, `upload_date`, `tag`. Responses: 200, 422, default.
`GET`	`/videos/{video}`	Optional bearer	Get a viewable video Parameters: `video` (required). Responses: 200, 404, default.
`GET`	`/videos/{video}/playback`	Optional bearer	Issue a playback session Selects only sources compatible with `X-PlayHub-Capabilities`, signs protected media URLs, and returns captions, chapters, ad decisions, resume state, and progress policy. Limited to 120/minute. Parameters: `video` (required), `X-PlayHub-Capabilities`. Responses: 200, 403, 406, 429, default.
`POST`	`/videos/{video}/receiver-playback`	Optional bearer	Issue a receiver-safe Cast manifest for a video Reauthorizes access at handoff time and returns bearer-free media URLs only when every required source origin is an explicitly configured, public HTTPS receiver origin. Native bearer tokens require `playback:read`. Protected URL lifetime covers the remaining duration plus a safety margin and is bounded by server policy. Direct external sources must be query- and fragment-free because this contract has no trusted external expiry metadata. Limited to 60/minute. Parameters: `video` (required). Request: `application/json`: `target`, `source_id`, `position_seconds`. Responses: 200, 401, 403, 404, 422, 429, default.
`GET`	`/videos/{video}/related`	Optional bearer	List related viewable videos Parameters: `video` (required), `page`, `per_page`. Responses: 200, 404, default.
`PUT`	`/videos/{video}/likes`	Native bearer required	Set the viewer's video like Idempotent; repeated requests preserve one like. Parameters: `video` (required). Responses: 200, default.
`DELETE`	`/videos/{video}/likes`	Native bearer required	Clear the viewer's video like Parameters: `video` (required). Responses: 200, default.
`POST`	`/videos/{video}/reports`	Native bearer required	Report a viewable video Idempotently records one report for the viewer. Owners cannot report their own video. Video and comment reports share a 10/hour limit per user or source IP. Parameters: `video` (required). Responses: 200, 403, default.

Endpoint reference

Comments

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/videos/{video}/comments`	Optional bearer	List top-level video comments Parameters: `video` (required), `page`, `per_page`. Responses: 200, 404, default.
`POST`	`/videos/{video}/comments`	Native bearer required	Create a comment or reply Limited to 30/minute per user or source IP. Parameters: `video` (required). Request: `multipart/form-data`: `body`, `parent_id`, `sticker_id`, `images`; `application/json`: `body`, `parent_id`, `sticker_id`. Responses: 201, 401, 422, default.
`GET`	`/videos/{video}/comments/{comment}/context`	Optional bearer	Resolve a visible video comment's ancestor IDs for opening its thread Ancestor IDs are ordered from the top-level comment to the immediate parent. An unavailable video, comment, or ancestor returns 404. Parameters: `video` (required), `comment` (required). Responses: 200, 404, default.
`GET`	`/comments/{comment}/replies`	Optional bearer	List replies to a comment Parameters: `comment` (required), `page`, `per_page`. Responses: 200, 404, default.
`PATCH`	`/comments/{comment}`	Native bearer required	Edit an owned comment Parameters: `comment` (required). Request: `application/json`: `body`. Responses: 200, 403, 422, default.
`DELETE`	`/comments/{comment}`	Native bearer required	Delete an authorized comment Parameters: `comment` (required). Responses: 204, 403, default.
`PUT`	`/comments/{comment}/likes`	Native bearer required	Set the viewer's comment like Parameters: `comment` (required). Responses: 200, default.
`DELETE`	`/comments/{comment}/likes`	Native bearer required	Clear the viewer's comment like Parameters: `comment` (required). Responses: 200, default.
`POST`	`/comments/{comment}/report`	Native bearer required	Report a comment Video and comment reports share a 10/hour limit per user or source IP. Parameters: `comment` (required). Responses: 200, default.
`POST`	`/comments/{comment}/pin`	Native bearer required	Toggle a comment's pinned state as the video owner Parameters: `comment` (required). Responses: 200, 403, default.

Endpoint reference

History

Method	Path (under /api/v1)	Authentication	Contract
`PUT`	`/videos/{video}/progress`	Native bearer required	Upsert watch progress idempotently `event_id` deduplicates client retries. Limited to 30/minute per user. Parameters: `video` (required). Request: `application/json`: `event_id`, `position_seconds`, `duration_seconds`, `state`, `occurred_at`. Responses: 200, 422, 429, default.
`GET`	`/history`	Native bearer required	List watch history Parameters: `status`, `page`, `per_page`. Responses: 200, default.
`DELETE`	`/history`	Native bearer required	Clear all watch history Responses: 200, default.
`GET`	`/history/continue-watching`	Native bearer required	List in-progress videos Parameters: `page`, `per_page`. Responses: 200, default.
`DELETE`	`/history/{video}`	Native bearer required	Remove one video from history Parameters: `video` (required). Responses: 200, default.

Endpoint reference

Community

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/community-posts`	Optional bearer	List viewable creator community posts Parameters: `page`, `per_page`, `filter`, `q`, `sort`. Responses: 200, default.
`GET`	`/community-posts/{communityPost}`	Optional bearer	Get a viewable creator community post Parameters: `communityPost` (required). Responses: 200, 404, default.
`PATCH`	`/community-posts/{communityPost}`	Native bearer required	update Community Post Parameters: `communityPost` (required), `communityPost` (required). Request: `application/json`: `body`, `type`, `url`, `video_id`, `poll_options`, `event_title`, `event_starts_at`, `event_ends_at`, `event_timezone`, `event_location`, `event_url`, `sale_enabled`, `sale_price`, `images`. Responses: 200, default.
`DELETE`	`/community-posts/{communityPost}`	Native bearer required	delete Community Post Parameters: `communityPost` (required), `communityPost` (required). Responses: 200, default.
`GET`	`/community-posts/{communityPost}/comments`	Optional bearer	List top-level comments on a viewable community post Parameters: `communityPost` (required), `page`, `per_page`. Responses: 200, 404, default.
`POST`	`/community-posts/{communityPost}/comments`	Native bearer required	Comment on a viewable community post or reply to its comment Parameters: `communityPost` (required). Request: `multipart/form-data`: `body`, `parent_id`, `sticker_id`, `images`; `application/json`: `body`, `parent_id`, `sticker_id`. Responses: 201, 401, 404, 422, default.
`GET`	`/community-posts/{communityPost}/comments/{comment}/context`	Optional bearer	Resolve a visible community comment's ancestor IDs for opening its thread Ancestor IDs are ordered from the top-level comment to the immediate parent. An unavailable post, comment, or ancestor returns 404. Parameters: `communityPost` (required), `comment` (required). Responses: 200, 404, default.
`PUT`	`/community-posts/{communityPost}/likes`	Native bearer required	Set the viewer's community post like Parameters: `communityPost` (required). Responses: 200, 404, default.
`DELETE`	`/community-posts/{communityPost}/likes`	Native bearer required	Clear the viewer's community post like Parameters: `communityPost` (required). Responses: 200, 404, default.
`GET`	`/profiles/{channel}/community-posts`	Optional bearer	List viewable community posts from a profile Parameters: `channel` (required), `page`, `per_page`, `filter`, `q`, `sort`. Responses: 200, 404, default.
`POST`	`/profiles/{channel}/community-posts`	Native bearer required	create Community Post Parameters: `channel` (required), `channel` (required). Request: `multipart/form-data`: `body`, `type`, `url`, `video_id`, `poll_options`, `event_title`, `event_starts_at`, `event_ends_at`, `event_timezone`, `event_location`, `event_url`, `sale_enabled`, `sale_price`, `images`. Responses: 201, default.
`GET`	`/community-posts/discovery`	Public	get Community Discovery Responses: 200, default.
`GET`	`/community-posts/options`	Native bearer required	get Community Options Responses: 200, default.
`GET`	`/library/community-bookmarks`	Native bearer required	list Community Bookmarks Parameters: `page`, `per_page`. Responses: 200, default.
`POST`	`/community-posts/{communityPost}/vote`	Native bearer required	vote Community Post Parameters: `communityPost` (required). Request: `application/json`: `option_index`. Responses: 200, default.
`POST`	`/community-posts/{communityPost}/bookmark`	Native bearer required	toggle Community Bookmark Parameters: `communityPost` (required). Responses: 200, default.
`POST`	`/community-posts/{communityPost}/share`	Native bearer required	share Community Post Parameters: `communityPost` (required). Responses: 200, default.
`GET`	`/community-posts/{communityPost}/voters`	Public	list Community Voters Parameters: `communityPost` (required), `page`, `per_page`. Responses: 200, default.
`GET`	`/comments/moderation`	Native bearer required	list Moderation Comments Parameters: `page`, `per_page`. Responses: 200, default.
`POST`	`/comments/{comment}/mute-user`	Native bearer required	mute Comment Author Parameters: `comment` (required). Responses: 200, default.
`POST`	`/community-posts/link-preview`	Native bearer required	preview Community Link Request: `application/json`: `url`. Responses: 200, default.

Endpoint reference

Shorts

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/shorts`	Optional bearer	List public Shorts with cursor pagination Parameters: `cursor`, `per_page`, `sort`. Responses: 200, default.
`GET`	`/shorts/{short}`	Optional bearer	Get a Short Parameters: `short` (required). Responses: 200, 404, default.
`GET`	`/shorts/{short}/playback`	Optional bearer	Issue a Short playback session Parameters: `short` (required), `X-PlayHub-Capabilities`. Responses: 200, 403, 406, default.
`POST`	`/shorts/{short}/receiver-playback`	Optional bearer	Issue a receiver-safe Cast manifest for the selected Short Uses the same authorization and receiver-origin policy as video handoff. Calling this endpoint is an explicit selected-item action; Shorts feed/preload responses never create receiver sessions. Parameters: `short` (required). Request: `application/json`: `target`, `source_id`, `position_seconds`. Responses: 200, 401, 403, 404, 422, 429, default.

Endpoint reference

Live

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/live-streams`	Optional bearer	List visible live, upcoming, or replay streams Parameters: `status`, `category`, `q`, `page`, `per_page`, `sort`, `date_range`, `following`, `channel`. Responses: 200, default.
`POST`	`/live-streams`	Native bearer required	Create or update the creator's draft stream Requires `live:publish`; TV clients are rejected. Limited to 60 writes/minute. Request: `application/json`: `title`, `description`, `tags`, `category_id`, `visibility`, `source_type`, `scheduled_at`, `appearance`, `stream_settings`, `monetization_settings`, `engagement_settings`. Responses: 200, 201, 403, 422, default.
`GET`	`/live/gifts`	Optional bearer	List enabled server-priced Live gifts Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/live/stickers`	Optional bearer	List enabled Super Stickers by category Parameters: `page`, `per_page`, `category`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/live-streams/{liveStream}`	Optional bearer	Get a visible live stream Parameters: `liveStream` (required). Responses: 200, 404, default.
`PUT`	`/live-streams/{liveStream}`	Native bearer required	Update an owned live stream Requires `live:publish`; TV clients are rejected. Parameters: `liveStream` (required). Request: `application/json`: `title`, `description`, `tags`, `category_id`, `visibility`, `source_type`, `scheduled_at`, `appearance`, `stream_settings`, `monetization_settings`, `engagement_settings`. Responses: 200, 403, 409, 422, default.
`POST`	`/live-streams/{liveStream}/join`	Optional bearer	Issue viewer or approved guest/cohost LiveKit grant Available while waiting for source or live. Only server-approved participants with live:publish may publish permitted camera/microphone sources. Preview grants always remain hidden subscribers and do not mutate audience or acceptance state. Room grants expire after 90 seconds; private no-store response. Parameters: `liveStream` (required), `preview`. Responses: 200, 403, 409, 422, 429, 503, default.
`POST`	`/live-streams/{liveStream}/creator-join`	Native bearer required	Issue a short-lived LiveKit publisher token Requires stream ownership and `live:publish`; TV tokens and TV client headers are rejected. The token may publish and subscribe but may not publish arbitrary data. Parameters: `liveStream` (required). Responses: 200, 403, 429, 503, default.
`GET`	`/live-streams/{liveStream}/messages`	Optional bearer	List live chat messages Public/optional-auth snapshot when chat is enabled. Audience/privacy restrictions are enforced; ended stream chat is read-only. Parameters: `liveStream` (required). Responses: 200, default.
`POST`	`/live-streams/{liveStream}/messages`	Native bearer required	Send a live chat message Requires live:view and an active stream. Followers-only, chat restrictions, moderation and slow-mode limits are enforced server-side. Mutations are not replayed automatically. Parameters: `liveStream` (required). Request: `application/json`: `body`. Responses: 201, 401, 403, 409, 422, 429, default.
`GET`	`/live-streams/{liveStream}/polls`	Optional bearer	List polls for a live stream Parameters: `liveStream` (required). Responses: 200, default.
`POST`	`/live-streams/{liveStream}/polls`	Native bearer required	Create or schedule an owned Live poll Parameters: `liveStream` (required). Request: `application/json`: `question`, `options`, `duration_minutes`, `starts_at`. Responses: 201, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/polls/{poll}/vote`	Native bearer required	Vote once in a live poll Requires live:view and audience access. The stream/poll must be active and unexpired; option ownership is validated and each user may vote only once. Parameters: `liveStream` (required), `poll` (required). Request: `application/json`: `option_id`. Responses: 200, 401, 403, 409, 422, default.
`POST`	`/live-streams/{liveStream}/participant-request`	Native bearer required	Request audience participation in a live stream Parameters: `liveStream` (required). Request: `application/json`: `media_mode`, `identity`. Responses: 200, 201, 401, 403, 404, 409, 422, 429, default.
`DELETE`	`/live-streams/{liveStream}/participant-request`	Native bearer required	Withdraw a stage request or leave approved participation Stop local capture before leaving; the server revokes stage approval and publishing access. Identity must belong to the authenticated requester. Parameters: `liveStream` (required). Request: `application/json`: `identity`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/schedule`	Native bearer required	Schedule an owned live stream Requires `live:publish`; TV clients are rejected. Parameters: `liveStream` (required). Request: `application/json`: `title`, `scheduled_at`. Responses: 200, 403, 422, default.
`GET`	`/live-streams/{liveStream}/thumbnail`	Native bearer required	Get thumbnail status for an owned live stream Parameters: `liveStream` (required). Responses: 200, 403, default.
`POST`	`/live-streams/{liveStream}/thumbnail`	Native bearer required	Upload a live thumbnail Requires `live:publish`; TV clients are rejected. Parameters: `liveStream` (required). Request: `multipart/form-data`: `thumbnail`, `only_if_missing`. Responses: 200, 403, 422, default.
`POST`	`/live-streams/{liveStream}/preflight`	Native bearer required	Validate client permissions and source readiness Requires `live:publish`; TV clients are rejected. Parameters: `liveStream` (required). Request: `application/json`: `camera_permission`, `microphone_permission`, `camera_label`, `microphone_label`, `width`, `height`, `frame_rate`, `upload_mbps`, `round_trip_ms`. Responses: 200, 403, 422, default.
`POST`	`/live-streams/{liveStream}/start`	Native bearer required	Start an owned live stream Prepares the LiveKit room or RTMP ingress. Requires `live:publish`; TV clients are rejected. Parameters: `liveStream` (required). Responses: 200, 403, 409, 503, default.
`POST`	`/live-streams/{liveStream}/activate`	Native bearer required	Mark a prepared live stream live Parameters: `liveStream` (required). Responses: 200, 403, 409, default.
`POST`	`/live-streams/{liveStream}/end`	Native bearer required	End an owned live stream Parameters: `liveStream` (required). Responses: 200, 403, 409, default.
`GET`	`/live-streams/{liveStream}/control-room`	Native bearer required	Get authorized owner or moderator control state Owner/moderator only while waiting for source or live. Ingest credentials and optional connect grant belong exclusively to the owner. Private no-store response. Parameters: `liveStream` (required), `connect`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/creator/live/options`	Native bearer required	get Creator Live Options Responses: 200, default.
`POST`	`/live-streams/{liveStream}/connection-probe`	Native bearer required	probe Creator Live Connection Parameters: `liveStream` (required). Request: `multipart/form-data`: `probe`. Responses: 201, default.
`POST`	`/live-streams/{liveStream}/messages/{message}/pin`	Native bearer required	Pin or unpin an owned visible chat message Owner-only and pinned_messages feature required. Message belongs to this stream. Request: `application/json`: `pinned`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`DELETE`	`/live-streams/{liveStream}/messages/{message}`	Native bearer required	Delete a scoped live chat message Owner/moderator only; message must belong to this stream. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/users/{user}/restrictions`	Native bearer required	Restrict stream entry or chat for a viewer Owner/moderator only, with host/cohost protection. Stream restriction removes room access and publishing approval; restrictions are indefinite until removed. Parameters: `liveStream` (required), `user` (required). Request: `application/json`: `type`, `reason`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`PUT`	`/live-streams/{liveStream}/polls/{poll}`	Native bearer required	Update or activate an owned Live poll Options cannot change after voting has begun; activating a poll closes the previous active poll. Request: `application/json`: `question`, `options`, `duration_minutes`, `starts_at`, `status`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`DELETE`	`/live-streams/{liveStream}/polls/{poll}`	Native bearer required	Delete an owned Live poll Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/live/options`	Optional bearer	Get configured Live capability options Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/live-streams/{liveStream}/room`	Optional bearer	Get read-only Live presentation context Does not issue a room token, accept an invite, record a viewer or expose ingest/recording secrets. Private no-store response. Parameters: `liveStream` (required). Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/contributions`	Native bearer required	Send a wallet contribution with an immutable retry key Requires audience access and an enabled monetary feature on a live stream. Rejects self-contribution, client prices/recipient, insufficient balance, disabled product and altered-key replay. Do not automatically replay financial mutations. Parameters: `liveStream` (required). Request: `application/json`: `type`, `amount`, `gift_id`, `super_sticker_id`, `message`, `idempotency_key`. Responses: 200, 201, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/participants/invite`	Native bearer required	Invite a guest or cohost by username Owner-only and participants must be enabled. Parameters: `liveStream` (required). Request: `application/json`: `username`, `role`. Responses: 201, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/participant-requests/{participantRequest}`	Native bearer required	Accept or decline a scoped stage request Owner/moderator only. Request must belong to this stream and still be pending. Guest grant permissions are reauthorized on join. Parameters: `liveStream` (required), `participantRequest` (required). Request: `application/json`: `decision`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/participants/action`	Native bearer required	Mute a published stage track or remove its participant Owner/moderator only. Host protection and participant/track/account ownership are checked server-side; mute_track and request_camera require track_sid. request_camera requires a muted camera owned by a participant who can still publish video, and sends only a targeted, expiring request for participant approval. It never remotely enables a camera. Parameters: `liveStream` (required). Request: `application/json`: `action`, `identity`, `track_sid`, `user_id`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/moderators`	Native bearer required	Assign a moderator and notify the real user Owner only; existing assignments do not resend notifications. Parameters: `liveStream` (required). Request: `application/json`: `username`. Responses: 200, 201, 401, 403, 404, 409, 422, 429, default.
`DELETE`	`/live-streams/{liveStream}/moderators/{user}`	Native bearer required	Remove a moderator assignment Owner only. Parameters: `liveStream` (required), `user` (required). Responses: 200, 401, 403, 404, 409, 422, 429, default.
`DELETE`	`/live-streams/{liveStream}/users/{user}/restrictions/{type}`	Native bearer required	Remove a stream or chat restriction Owner/moderator only. Parameters: `liveStream` (required), `user` (required), `type` (required). Responses: 200, 401, 403, 404, 409, 422, 429, default.
`PUT`	`/live-streams/{liveStream}/engagement`	Native bearer required	Update configured pinned text and alerts Owner only. Feature flags and label limits are server-authoritative. Parameters: `liveStream` (required). Request: `application/json`: `pinned_message`, `alerts`, `labels`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`PUT`	`/live-streams/{liveStream}/chat-settings`	Native bearer required	Update active stream chat rules Owner only while waiting for source or live. Room participants receive stream_updated. Parameters: `liveStream` (required). Request: `application/json`: `enable_chat`, `slow_mode`, `slow_mode_interval`, `followers_only`, `unique_chat`, `chat_moderation`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`GET`	`/live-streams/{liveStream}/polls/{poll}/voters`	Native bearer required	Get paginated voter identities and chosen options Owner-only. Poll must belong to this stream; identities are not exposed in the public results. Parameters: `liveStream` (required), `poll` (required), `page`, `per_page`. Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/rtmp-ingress`	Native bearer required	Prepare private OBS RTMP ingest credentials Owner with live:publish only; RTMP source required. Private no-store publishing secret; never include in public room data. Parameters: `liveStream` (required). Responses: 200, 401, 403, 404, 409, 422, 429, 503, default.
`POST`	`/live-streams/{liveStream}/ads`	Native bearer required	Request a configured Live ad impression Audience-only; excludes stream owner. Real enabled Live ad configuration and server frequency checks are required. Separate from native VOD IMA accounting. Parameters: `liveStream` (required). Responses: 200, 401, 403, 404, 409, 422, 429, default.
`POST`	`/live-streams/{liveStream}/ads/{impression}/complete`	Native bearer required	Complete an owned Live ad impression once Requires the authenticated viewer and same stream/impression. Server enforces elapsed duration, 15-minute completion window and atomic one-time creator credit. Interrupted ads are not completed. Parameters: `liveStream` (required), `impression` (required). Responses: 200, 401, 403, 404, 409, 410, 422, 429, default.

Endpoint reference

Profiles

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/profiles/{channel}`	Optional bearer	Get a visible creator profile Parameters: `channel` (required). Responses: 200, 404, default.
`GET`	`/mentions/{handle}`	Optional bearer	Resolve a mentioned username or channel slug to a visible profile Case-insensitive exact match without the leading @. Returns 404 for unknown, hidden, channel-less, or ambiguous handles rather than guessing between a username and another person's channel slug. Parameters: `handle` (required). Responses: 200, 404, default.
`GET`	`/profiles/{channel}/videos`	Optional bearer	List a profile's public videos Parameters: `channel` (required), `content_type`, `page`, `per_page`. Responses: 200, 404, default.
`GET`	`/profiles/{channel}/playlists`	Optional bearer	List a profile's visible playlists Parameters: `channel` (required), `page`, `per_page`. Responses: 200, default.
`GET`	`/profiles/{channel}/subscribers`	Optional bearer	List visible subscribers Lists subscribers whose own profiles are public and active. The channel owner's `showSubscriptions` preference hides channels they follow, not people subscribed to their channel. Parameters: `channel` (required), `page`, `per_page`. Responses: 200, 404, default.
`POST`	`/profiles/{channel}/reports`	Native bearer required	Report a public profile for review Idempotently records one report per viewer and profile. Own profiles cannot be reported. No reason field is defined by the existing report model. Parameters: `channel` (required). Responses: 200, 403, 404, default.
`PUT`	`/profiles/{channel}/subscription`	Native bearer required	Subscribe to a creator idempotently Parameters: `channel` (required). Responses: 200, 403, default.
`DELETE`	`/profiles/{channel}/subscription`	Native bearer required	Unsubscribe from a creator idempotently Parameters: `channel` (required). Responses: 200, default.

Endpoint reference

Playlists

Method	Path (under /api/v1)	Authentication	Contract
`POST`	`/playlists`	Native bearer required	Create a playlist Request: `application/json`: `title`, `description`, `privacy`, `color`, `cover_video_id`, `video_ids`. Responses: 201, 422, default.
`GET`	`/playlists/{playlist}`	Optional bearer	Get a visible playlist and paginated videos Parameters: `playlist` (required), `page`, `per_page`, `sort`. Responses: 200, 404, default.
`PATCH`	`/playlists/{playlist}`	Native bearer required	Update an owned playlist Parameters: `playlist` (required). Request: `application/json`: `title`, `description`, `privacy`, `color`, `cover_video_id`, `video_ids`. Responses: 200, 403, 422, default.
`DELETE`	`/playlists/{playlist}`	Native bearer required	Delete an owned playlist Parameters: `playlist` (required). Responses: 204, 403, default.
`PUT`	`/playlists/{playlist}/videos/{video}`	Native bearer required	Add a viewable video to an owned playlist idempotently Parameters: `playlist` (required), `video` (required). Responses: 200, default.
`DELETE`	`/playlists/{playlist}/videos/{video}`	Native bearer required	Remove a video from an owned playlist idempotently A slug outside the owned playlist and a nonexistent slug both succeed with `video_id: null`; unrelated private videos are not resolved. Parameters: `playlist` (required), `video` (required). Responses: 200, default.

Endpoint reference

Search

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/search`	Optional bearer	Search videos, Shorts, creators, live streams, playlists, or categories Limited to 60/minute per user or IP. Whitespace-only queries are rejected. `all` returns compact video, Short, creator, live, and category sections; a specific type returns a paginated list. Filters apply to videos and shorts types only. Parameters: `q` (required), `type`, `sort`, `upload_date`, `duration`, `resolution`, `features`, `category`, `page`, `per_page`. Responses: 200, 422, 429, default.
`GET`	`/search/suggestions`	Optional bearer	Get short-lived search suggestions Returns up to 10 suggestions (public video titles, channel names, and enabled category names) matching the query. Cached server-side for 30 seconds. Parameters: `q` (required). Responses: 200, 422, 429, default.

GET

/search

Optional bearer

Search videos, Shorts, creators, live streams, playlists, or categories

Limited to 60/minute per user or IP. Whitespace-only queries are rejected. all returns compact video, Short, creator, live, and category sections; a specific type returns a paginated list. Filters apply to videos and shorts types only.

Parameters: q (required), type, sort, upload_date, duration, resolution, features, category, page, per_page.

Responses: 200, 422, 429, default.

GET

/search/suggestions

Optional bearer

Get short-lived search suggestions

Returns up to 10 suggestions (public video titles, channel names, and enabled category names) matching the query. Cached server-side for 30 seconds.

Parameters: q (required).

Responses: 200, 422, 429, default.

Endpoint reference

Advertising

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/ads/configuration`	Optional bearer	Get public player ad configuration Responses: 200, default.
`POST`	`/ads/resolve`	Optional bearer	Resolve eligible ads for a video playback Applies authoritative server-side eligibility and frequency rules. Resolution is limited to 10/minute and 60/hour per user or source IP. Anonymous viewers can receive playable ads but never payout-bearing impression credentials. Request: `application/json`: `video_id`, `ad_ids`. Responses: 200, 403, 422, default.
`POST`	`/ads/impressions/{impression}/complete`	Native bearer required	Complete a signed ad impression Idempotently completes a valid signed impression after the required play time. Requires the original authenticated viewer and the `playback:read` ability; the response never exposes settlement amounts. Completion is limited to 60/minute and 300/hour per user. Parameters: `impression` (required). Request: `application/json`: `token`. Responses: 200, 401, 403, 409, 410, 422, 429, default.

GET

/ads/configuration

Optional bearer

Get public player ad configuration

Responses: 200, default.

POST

/ads/resolve

Optional bearer

Resolve eligible ads for a video playback

Applies authoritative server-side eligibility and frequency rules. Resolution is limited to 10/minute and 60/hour per user or source IP. Anonymous viewers can receive playable ads but never payout-bearing impression credentials.

Request: application/json: video_id, ad_ids.

Responses: 200, 403, 422, default.

POST

/ads/impressions/{impression}/complete

Native bearer required

Complete a signed ad impression

Idempotently completes a valid signed impression after the required play time. Requires the original authenticated viewer and the playback:read ability; the response never exposes settlement amounts. Completion is limited to 60/minute and 300/hour per user.

Parameters: impression (required).

Request: application/json: token.

Responses: 200, 401, 403, 409, 410, 422, 429, default.

Endpoint reference

Account

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/account`	Native bearer required	Get the caller's complete account Requires the `account:read` native token ability. Responses: 200, 401, 403, default.
`DELETE`	`/account`	Native bearer required	Permanently delete the caller's account Requires `account:write`, literal confirmation `DELETE`, and the current password for local/password accounts. The operation deletes account-owned data and revokes sessions and tokens. Request: `application/json`: `confirmation`, `current_password`. Responses: 204, 403, 422, default.
`PATCH`	`/account/profile`	Native bearer required	Partially update identity and channel profile fields Changing email clears email verification. Requires `account:write`. Request: `application/json`: `name`, `username`, `email`, `gender`, `date_of_birth`, `channel_name`, `channel_slug`, `bio`, `about`. Responses: 200, 403, 422, default.
`PATCH`	`/account/settings`	Native bearer required	Partially merge account preferences Requires `account:write`. Request: `application/json`: `profile`, `preferences`, `playback`, `appearance`. Responses: 200, 403, 422, default.
`POST`	`/account/avatar`	Native bearer required	Replace the account and channel avatar JPEG, PNG, or WebP up to 5 MiB. Requires `account:write`. Request: `multipart/form-data`: `avatar`. Responses: 200, 413, 422, default.
`DELETE`	`/account/avatar`	Native bearer required	Remove the account and channel avatar Responses: 200, default.
`POST`	`/account/cover`	Native bearer required	Replace the caller's channel cover JPEG, PNG, or WebP up to 5 MiB and 8192 pixels per dimension. Requires `account:write`. Request: `multipart/form-data`: `cover`. Responses: 200, 413, 422, default.
`DELETE`	`/account/cover`	Native bearer required	Remove the caller's channel cover Responses: 200, default.
`POST`	`/account/password`	Native bearer required	Change the account password Requires `account:write`; limited to 5/minute per IP. Request: `application/json`: `current_password`, `password`, `password_confirmation`. Responses: 200, 422, 429, default.
`POST`	`/account/two-factor/setup`	Native bearer required	Prepare email or SMS two-factor authentication Request: `application/json`: `two_factor_method`, `two_factor_phone`. Responses: 200, 422, default.
`POST`	`/account/two-factor/enable`	Native bearer required	Confirm and enable two-factor authentication Request: `application/json`: `two_factor_code`. Responses: 200, 422, default.
`POST`	`/account/two-factor/disable`	Native bearer required	Disable two-factor authentication Request: `application/json`: `two_factor_code`. Responses: 200, 422, default.
`POST`	`/account/upgrade-creator`	Native bearer required	Request or complete creator upgrade Requires `account:write`; limited to 10/minute. Responses: 200, 403, 429, default.
`GET`	`/me/capabilities`	Native bearer required	get Account Capabilities Responses: 200, default.
`GET`	`/me/plan`	Native bearer required	get Account Plan Responses: 200, default.
`GET`	`/me/wallet`	Native bearer required	get Account Wallet Responses: 200, default.
`GET`	`/me/wallet/transactions`	Native bearer required	list Wallet Transactions Parameters: `page`, `per_page`, `type`. Responses: 200, default.
`GET`	`/me/billing-history`	Native bearer required	list Billing History Parameters: `page`, `per_page`. Responses: 200, default.
`POST`	`/me/wallet/withdrawals`	Native bearer required	request Wallet Withdrawal Request: `application/json`: `amount`, `method`, `account`, `note`, `confirmed`, `idempotency_key`. Responses: 201, default.
`GET`	`/creator/earnings`	Native bearer required	get Creator Earnings Parameters: `page`, `per_page`, `source`. Responses: 200, default.
`GET`	`/localization`	Public	get Localization Catalog Responses: 200, default.
`GET`	`/localization/{locale}`	Public	get Localization Pack Parameters: `locale` (required). Responses: 200, default.
`GET`	`/content-pages`	Public	list Content Navigation Parameters: `locale`. Responses: 200, default.
`GET`	`/discovery/options`	Public	get Discovery Options Responses: 200, default.
`GET`	`/library/subscription-feed`	Native bearer required	list Subscription Feed Parameters: `page`, `per_page`, `section`, `filter`, `type`. Responses: 200, default.
`GET`	`/me/billing-information`	Native bearer required	get Billing Information Responses: 200, default.
`PUT`	`/me/billing-information`	Native bearer required	update Billing Information Request: `application/json`: `name`, `email`, `company`, `phone`, `address_line_1`, `address_line_2`, `city`, `region`, `postal_code`, `country`. Responses: 200, default.

Endpoint reference

Push

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/push-devices`	Native bearer required	List active push registrations Requires the mobile `account:write` ability. Responses: 200, default.
`POST`	`/push-devices`	Native bearer required	Register or refresh an encrypted push token FCM supports Android production registrations. APNs supports iOS sandbox and production registrations. The raw token is accepted only on write and is never returned. Request: `application/json`: `provider`, `platform`, `environment`, `token`, `device_id`, `device_name`, `app_version`, `app_identifier`, `locale`. Responses: 200, 201, 422, 429, default.
`DELETE`	`/push-devices`	Native bearer required	Revoke all push registrations Responses: 200, default.
`DELETE`	`/push-devices/{pushDevice}`	Native bearer required	Revoke an owned push registration Parameters: `pushDevice` (required). Responses: 200, 404, default.

Endpoint reference

Library

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/library`	Native bearer required	Get compact library rows, total counts, and links Responses: 200, 401, default.
`GET`	`/library/watch-later`	Native bearer required	List watch-later videos Parameters: `page`, `per_page`, `sort`, `type`. Responses: 200, default.
`PUT`	`/library/watch-later/{video}`	Native bearer required	Add a video to watch later idempotently Parameters: `video` (required). Responses: 200, default.
`DELETE`	`/library/watch-later/{video}`	Native bearer required	Remove a video from watch later idempotently Parameters: `video` (required). Responses: 200, default.
`GET`	`/library/liked-videos`	Native bearer required	List liked videos Parameters: `page`, `per_page`, `sort`, `type`. Responses: 200, default.
`GET`	`/library/purchased-videos`	Native bearer required	List videos purchased by the caller Parameters: `page`, `per_page`. Responses: 200, default.
`GET`	`/library/subscriptions`	Native bearer required	List subscribed creator channels Parameters: `page`, `per_page`. Responses: 200, default.
`GET`	`/library/subscription-videos`	Native bearer required	List recent videos from subscribed channels Parameters: `page`, `per_page`. Responses: 200, default.
`GET`	`/library/playlists`	Native bearer required	List the caller's playlists Parameters: `page`, `per_page`, `sort`. Responses: 200, default.
`GET`	`/library/playlist-videos`	Native bearer required	Search the caller's uploaded videos for playlist editing Parameters: `page`, `per_page`, `q`. Responses: 200, default.
`GET`	`/library/favorite-channels`	Native bearer required	list Favorite Channels Parameters: `page`, `per_page`. Responses: 200, default.
`GET`	`/library/favorite-channels/videos`	Native bearer required	list Favorite Channel Videos Parameters: `page`, `per_page`. Responses: 200, default.
`PUT`	`/profiles/{channel}/favorite`	Native bearer required	save Favorite Channel Parameters: `channel` (required). Responses: 200, default.
`DELETE`	`/profiles/{channel}/favorite`	Native bearer required	remove Favorite Channel Parameters: `channel` (required). Responses: 200, default.

Endpoint reference

Messages

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/messages/users`	Native bearer required	Find users who can receive a private message from the viewer Search results include conversation_id when the two users already have a conversation. Parameters: `q`, `user_id`. Responses: 200, 401, default.
`GET`	`/messages`	Native bearer required	List the viewer's private conversations Includes one authoritative unread_count across all conversations. Does not load each thread. Parameters: `page`, `per_page`. Responses: 200, 401, default.
`POST`	`/messages`	Native bearer required	Send the first message to an allowed recipient Request: `application/json`: `recipient_id`, `body`; `multipart/form-data`: `recipient_id`, `body`, `images`. Responses: 201, 403, 422, default.
`GET`	`/messages/{conversation}`	Native bearer required	Get a conversation without marking it read Parameters: `conversation` (required). Responses: 200, 404, default.
`GET`	`/messages/{conversation}/messages`	Native bearer required	List messages from newest to oldest Parameters: `conversation` (required), `page`, `per_page`. Responses: 200, 404, default.
`POST`	`/messages/{conversation}/messages`	Native bearer required	Send a message in an existing conversation Parameters: `conversation` (required). Request: `application/json`: `body`; `multipart/form-data`: `body`, `images`. Responses: 201, 403, 404, 422, default.
`PUT`	`/messages/{conversation}/read`	Native bearer required	Mark incoming messages in this conversation as read Parameters: `conversation` (required). Responses: 200, 404, default.

Endpoint reference

Mutes

Method Path (under /api/v1) Authentication Contract

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/mutes`	Native bearer required	List users whose notifications the viewer muted Responses: 200, 401, default.
`PUT`	`/mutes/{user}`	Native bearer required	Mute notifications from a user This does not block the user, hide their content, or prevent messages. Parameters: `user` (required). Responses: 200, 422, default.
`DELETE`	`/mutes/{user}`	Native bearer required	Unmute notifications from a user Parameters: `user` (required). Responses: 200, default.

GET

/mutes

Native bearer required

List users whose notifications the viewer muted

Responses: 200, 401, default.

PUT

/mutes/{user}

Native bearer required

Mute notifications from a user

This does not block the user, hide their content, or prevent messages.

Parameters: user (required).

Responses: 200, 422, default.

DELETE

/mutes/{user}

Native bearer required

Unmute notifications from a user

Parameters: user (required).

Responses: 200, default.

Endpoint reference

Notifications

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/notifications`	Native bearer required	List in-app notifications Parameters: `unread_only`, `type`, `page`, `per_page`. Responses: 200, default.
`PUT`	`/notifications/read-all`	Native bearer required	Mark all notifications read Responses: 200, default.
`GET`	`/notifications/settings`	Native bearer required	Get notification preferences Responses: 200, default.
`PATCH`	`/notifications/settings`	Native bearer required	Partially update notification preferences Request: `application/json`: `comments`, `replies`, `mentions`, `liveReminders`, `uploads`, `subscriptions`, `newsletter`. Responses: 200, 422, default.
`PUT`	`/notifications/{notification}/read`	Native bearer required	Mark one owned notification read Parameters: `notification` (required). Responses: 200, 404, default.
`DELETE`	`/notifications/{notification}`	Native bearer required	Delete one owned notification Parameters: `notification` (required). Responses: 204, 404, default.

Endpoint reference

Uploads

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/uploads/capabilities`	Native bearer required	Get creator upload limits and supported formats Requires the mobile `uploads:write` token ability. Current transport is server-proxied chunk upload; direct-to-cloud is reported false. Responses: 200, 403, default.
`POST`	`/uploads/sessions`	Native bearer required	Create a chunked upload session `total_chunks` must equal `ceil(file_size / chunk_size)`. Supported extensions are MP4, MOV, M4V, WebM, and MKV. Request: `application/json`: `client_upload_id`, `file_name`, `file_size`, `mime_type`, `chunk_size`, `total_chunks`. Responses: 201, 403, 422, default.
`GET`	`/uploads/sessions/{uploadSession}`	Native bearer required	Get an owned upload session Parameters: `uploadSession` (required). Responses: 200, 403, 404, default.
`DELETE`	`/uploads/sessions/{uploadSession}`	Native bearer required	Cancel an upload session before assembly or processing Parameters: `uploadSession` (required). Responses: 200, 409, default.
`POST`	`/uploads/sessions/{uploadSession}/chunks`	Native bearer required	Upload or replace one session chunk Multipart upload. The chunk index is zero-based and the file limit equals the server-configured chunk size, 8 MiB by default. Parameters: `uploadSession` (required). Request: `multipart/form-data`: `index`, `chunk`. Responses: 200, 409, 413, 422, default.
`POST`	`/uploads/sessions/{uploadSession}/complete`	Native bearer required	Assemble an upload and enqueue video processing All chunks must exist. Shorts require portrait dimensions and a duration of at most 60 seconds. Processing is asynchronous. Parameters: `uploadSession` (required). Request: `multipart/form-data`: `publish_as_draft`, `title`, `description`, `tags`, `category_id`, `language_id`, `playlist_id`, `playlist_title`, `scheduled_at`, `made_for_kids`, `monetization_enabled`, `sale_enabled`, `sale_price`, `visibility`, `content_type`, `video_width`, `video_height`, `duration_seconds`, `thumbnail`, `captions`, `chapters_enabled`, `chapters`; `application/json`: `publish_as_draft`, `title`, `description`, `tags`, `category_id`, `language_id`, `playlist_id`, `playlist_title`, `scheduled_at`, `made_for_kids`, `monetization_enabled`, `sale_enabled`, `sale_price`, `visibility`, `content_type`, `video_width`, `video_height`, `duration_seconds`, `thumbnail`, `captions`, `chapters_enabled`, `chapters`. Responses: 201, 409, 422, default.

Endpoint reference

Creator

Method	Path (under /api/v1)	Authentication	Contract
`GET`	`/creator/options`	Native bearer required	getCreatorOptions Responses: 200, default.
`GET`	`/creator/dashboard`	Native bearer required	getCreatorDashboard Responses: 200, default.
`GET`	`/creator/videos`	Native bearer required	listCreatorVideos Parameters: `tab`, `page`, `q`, `visibility`, `status`, `monetization`, `sort`. Responses: 200, default.
`GET`	`/creator/videos/{video}`	Native bearer required	getCreatorVideo Parameters: `video` (required). Responses: 200, default.
`PATCH`	`/creator/videos/{video}`	Native bearer required	updateCreatorVideo Parameters: `video` (required). Request: `application/json`: `title`, `description`, `tags`, `category_id`, `language_id`, `visibility`, `scheduled_at`, `publish_as_draft`, `made_for_kids`, `monetization_enabled`, `chapters_enabled`, `chapters`, `playlist_title`. Responses: 200, default.
`DELETE`	`/creator/videos/{video}`	Native bearer required	deleteCreatorVideo Parameters: `video` (required). Responses: 200, default.
`POST`	`/creator/videos/{video}/retry`	Native bearer required	retryCreatorVideo Parameters: `video` (required). Responses: 200, default.
`POST`	`/creator/videos/{video}/thumbnail`	Native bearer required	setCreatorThumbnail Parameters: `video` (required). Request: `multipart/form-data`: `thumbnail`. Responses: 200, default.
`POST`	`/creator/videos/{video}/caption`	Native bearer required	setCreatorCaption Parameters: `video` (required). Request: `multipart/form-data`: `caption`, `language`, `label`, `default`. Responses: 200, default.
`DELETE`	`/creator/videos/{video}/caption`	Native bearer required	deleteCreatorCaption Parameters: `video` (required). Responses: 200, default.
`GET`	`/creator/analytics`	Native bearer required	getCreatorAnalytics Parameters: `range`. Responses: 200, default.
`GET`	`/creator/videos/{video}/analytics`	Native bearer required	getCreatorVideoAnalytics Parameters: `video` (required), `range`. Responses: 200, default.
`GET`	`/creator/channel`	Native bearer required	getCreatorChannel Responses: 200, default.
`PATCH`	`/creator/channel`	Native bearer required	updateCreatorChannel Request: `application/json`: `name`, `slug`, `bio`, `about`, `website`, `socials`. Responses: 200, default.
`POST`	`/creator/channel/artwork`	Native bearer required	setCreatorChannelArtwork Request: `multipart/form-data`: `kind`, `image`. Responses: 200, default.
`POST`	`/creator/imports`	Native bearer required	importCreatorVideo Request: `application/json`: `provider`, `url`, `title`, `description`, `tags`, `category_id`, `visibility`, `scheduled_at`. Responses: 200, default.
`GET`	`/creator/live`	Native bearer required	listCreatorLive Parameters: `page`. Responses: 200, default.