Contents
On this page

REST API - Plugixa Stream

Everything the admin app and the Watch app do goes through one REST namespace, plugixa-stream/v1. You can call the same routes yourself: to sync a catalogue from another system, build your own front end or mobile app, or automate publishing. Every permission the interface enforces is enforced at the endpoint, not in the page.

Routes that come from Pro PRO (coins, VIP, reviews, profiles, screens, people, custom fields, TMDB, AI subtitles, Bunny Stream, encoding) exist only when Pro is installed. On the free plugin they answer 404 rest_no_route.

Base URL

https://your-site.example/wp-json/plugixa-stream/v1

On a site with plain permalinks, pass the route as a parameter instead:

https://your-site.example/?rest_route=/plugixa-stream/v1/series

Two kinds of route

Kind Paths Who calls them
Admin routes /admin/... The admin app, or your scripts. Each one checks one of the plugin’s capabilities.
Viewer routes /home, /series, /episodes/{id}/play, /me/... and the other routes without /admin The Watch app, or your own front end. Public, or open to any signed-in user for their own data.

A viewer route never trusts the client about access. Whether an episode plays is decided on the server, for each request, by Play Episode: the lock icons in an episode list are the same answer, shown in advance.

Authentication

The plugin has no API keys of its own. A request runs as a WordPress user, or as a guest.

Caller How it signs in What it reaches
Anyone Nothing The published catalogue, free episodes, people pages PRO and published reviews PRO
A signed-in viewer Application Password, or the login cookie plus an X-WP-Nonce header Their own progress, My List, likes, wallet PRO, profiles PRO, screens PRO and reviews PRO, and the episodes they unlocked
A back-office user The same, plus the plugin’s capabilities The /admin/... routes their capabilities allow

Application Passwords

For scripts and other servers. Create one under Users -> Profile -> Application Passwords for the WordPress user the script should act as, then send it with HTTP Basic authentication:

curl -s "https://your-site.example/wp-json/plugixa-stream/v1/admin/series" \
  -u "$WP_USER:$WP_APP_PASSWORD"

Application Passwords are a WordPress feature, not the plugin’s: WordPress offers them on sites served over HTTPS, and a security plugin or host can switch them off.

For pages on the same site. The Watch app and the admin app use the visitor’s login cookie and send the REST nonce in an X-WP-Nonce header; WordPress checks the nonce before the route runs. The Watch app only receives a nonce when the visitor is signed in. Without the header, a cookie request is treated as a guest.

Profiles and screens

The active profile PRO and the current screen belong to a login session. A request signed with an Application Password has no session, so it always acts as the account’s own profile, and Switch Profile changes nothing for it. Coins, unlocks and VIP belong to the account, never to a profile.

Capabilities

Admin routes check one of the plugin’s capabilities.

Capability Allows
plugixa_stream_view Reading back-office data: lists, records, the dashboard, settings, orders and viewers PRO
plugixa_stream_create Creating titles and episodes
plugixa_stream_edit Changing them, home rows, terms, credits PRO, prices PRO, and moderating reviews PRO
plugixa_stream_delete Deleting titles, episodes and people PRO
plugixa_stream_manage_settings Settings, payment gateways PRO, refunds PRO, coin adjustments PRO, coupons PRO and service keys PRO

The plugin gives these capabilities to administrators when it is activated, and a user with WordPress’s manage_options holds all of them. Give them to another role with a role editor if someone else should manage the catalogue. A user who holds any of them also gets plugixa_stream_manage, which shows the plugin’s menu; it is never stored.

A few routes ask for more:

Route Also needs
Update Settings when it changes delete_data_on_uninstall manage_options
Import Catalogue and the TMDB import routes PRO plugixa_stream_create, plugixa_stream_edit and upload_files
Update Encoding Settings PRO when it changes ffmpeg_path manage_options (otherwise the path is ignored)

Responses

Every successful response is wrapped the same way:

{
  "success": true,
  "data": { "id": 2681, "title": "Sintel", "kind": "movie" },
  "meta": { "total": 24, "pages": 1 }
}

meta is only present when it has something in it. Three routes answer otherwise: the two payment webhooks PRO answer {"received": true}, and the PayPal return PRO and the email unsubscribe link PRO, opened in a browser, answer with a 302 redirect.

Titles and episodes come in two shapes. The public shape, from the viewer routes, holds only what a visitor may see and never a stream URL or a video’s source. The back-office shape, from the /admin/... routes, holds every editable field as stored.

Dates are not all in one form; each endpoint page says which it uses:

Form Used by
UTC, 2026-11-17 09:30:00 Progress, coin history, orders, subscriptions PRO
Site time, 2026-11-17 10:30:00 A title’s modified_at, a scheduled episode’s publish_at
ISO 8601 in UTC, 2026-11-17T09:30:00+00:00 Reviews PRO
Unix time Signed URL expiry, webhook arrivals, encoding jobs PRO

The money lists of the admin PRO (orders, subscriptions, coin history) return rows as the database stores them, so their numbers are strings: "amount": "1499".

Lists and pagination

Paged lists accept the same parameters:

Parameter Type Default Description
page integer 1 Page to return, from 1
per_page integer 24 Rows per page, 1 to 100
search string Words to look for, in the fields each endpoint lists

On Browse Titles, List Series and Watch History, a per_page outside 1 to 100 is refused with 400; the other lists bring it back into range. Totals, when a list has them, are in meta.total and meta.pages, not in headers. A list without meta has no total: ask for the next page until one comes back shorter than per_page. Each endpoint page says which parameters and totals it has.

Rate limiting

The routes a bot would hammer are limited per signed-in account, or for guests per IP address (stored only as a hash). The window is one minute, and each kind of request has its own count.

Count Routes Limit
play Play Episode 60 a minute
unlock PRO Unlock Episode, Unlock Series 60 a minute
reward PRO Daily Check-in 60 a minute
coupon PRO Check Coupon 60 a minute
review PRO Rate a Title, Report Review 60 a minute
screens PRO Screen Heartbeat, Watch Here 60 a minute

Over the limit, a request answers 429 plugixa_stream_rate_limited until the minute is over. Change a limit, or switch it off with 0, with the plugixa_stream_rate_limit filter:

add_filter( 'plugixa_stream_rate_limit', function ( int $limit, string $bucket ) {
	return 'play' === $bucket ? 120 : $limit;
}, 10, 2 );

Separately, five wrong profile PINs PRO lock PIN checks for 15 minutes. Other routes have no limit.

Endpoints

Resource Endpoints
Catalog Get Home, Browse Titles, Get Title, List Genres, List Years
Playback Play Episode
Progress Save Progress, Continue Watching, Watch History, Get My List, Update My List
Series List Series, Create Series, Get Series, Update Series, Delete Series
Episodes List Episodes, Create Episode, Get Episode, Update Episode, Delete Episode, Reorder Episodes, Set Episode Access
Home rows Get Home Rows, Save Home Rows
Terms List Terms, Create Term
CSV Export Catalogue, Import Catalogue
Dashboard Get Dashboard
Settings Get Settings, Update Settings
Video services List Video Services, Test Video Service
Wallet PRO Get Wallet, Get Coin History, Daily Check-in
Unlocks PRO Unlock Episode, Unlock Series
Checkout PRO Start Checkout, Check Coupon, Cancel My VIP, PayPal Return
Webhooks PRO Stripe Webhook, PayPal Webhook
Payments PRO Get Payment Settings, Update Payment Settings, Test Payment Gateway
Viewers PRO List Viewers, Get Viewer, Adjust Coins
Orders PRO List Orders, Refund Order
Coupons PRO List Coupons, Save Coupon, Delete Coupon
Subscriptions PRO List Subscriptions, Cancel Subscription
Prices PRO Get Series Prices, Update Series Prices
Reviews PRO List Reviews, Rate a Title, Delete My Review, Report Review, List All Reviews, Moderate Review, Delete Review
Profiles PRO List Profiles, Create Profile, Update Profile, Delete Profile, Switch Profile, Set Profile PIN
Screens PRO List Screens, Screen Heartbeat, Watch Here, Stop Screen
Email PRO Get Email Preferences, Update Email Preferences, Email Unsubscribe, Send Test Email
People PRO Get Person, List People, Create Person, Update Person, Delete Person, Get Credits, Save Credits
Custom fields PRO List Custom Fields, Save Custom Fields, Get Custom Field Values, Save Custom Field Values
TMDB PRO Get TMDB Settings, Update TMDB Settings, Search TMDB, Preview TMDB Title, Import from TMDB, Import TMDB Season, Get TMDB Link
AI subtitles PRO Get AI Settings, Update AI Settings, Translate Subtitles, Transcribe Episode
Bunny Stream PRO Get Bunny Settings, Update Bunny Settings, Create Bunny Upload, Get Bunny Video
Encoding PRO Get Encoding Settings, Update Encoding Settings, Get Encoding Job, Encode Episode, Cancel Encoding

Subtitle and audio tracks PRO have no routes of their own: they are fields of Create Episode and Update Episode. Video ads PRO have none either: their plan rides on the answer of Play Episode, and their settings are ordinary settings.

Webhooks

The plugin receives webhooks from two payment gateways only, with Pro: Stripe posts to /webhooks/stripe and PayPal to /webhooks/paypal. Each delivery is checked against the gateway’s signature before anything is read. See Stripe Webhook and PayPal Webhook. The plugin sends no webhooks of its own; to react to its events in PHP, use its hooks.

Errors

Errors use the standard WordPress shape:

{
  "code": "plugixa_stream_not_found",
  "message": "Not found.",
  "data": { "status": 404 }
}

These can come back from any endpoint. Each endpoint page lists its own errors on top of them.

Status Code When
401 plugixa_stream_forbidden An admin route, signed out.
403 plugixa_stream_forbidden Signed in, but the user lacks the capability.
401 plugixa_stream_login_required A viewer route that needs a signed-in user, signed out.
404 plugixa_stream_not_found No such record, or one the caller may not see: drafts do not exist for viewers.
422 plugixa_stream_invalid A field failed validation. On titles and episodes, data.field names it.
429 plugixa_stream_rate_limited Too many requests of one kind in a minute. See Rate limiting.
401 incorrect_password WordPress refused the Application Password. Other WordPress sign-in codes are possible.
403 rest_cookie_invalid_nonce Cookie sign-in with a stale nonce.
404 rest_no_route No such route or method, or a Pro route on the free plugin.
400 rest_invalid_param A declared parameter failed validation, for example per_page above 100.
400 rest_missing_callback_param A required parameter is missing.

Filtering what comes back

Filters let you change payloads and decisions in PHP without touching the routes:

Filter Changes
plugixa_stream_filter_output Every successful payload, with the kind of record it holds
plugixa_stream_home The home payload, with the viewer’s id (0 for a guest)
plugixa_stream_series_detail What a title’s screen shows about the title, the same for every viewer
plugixa_stream_series_viewer_state The viewer part of a title: what this viewer has done with it
plugixa_stream_can_play Whether a viewer may play an episode. Never return false for a free one
plugixa_stream_locked_offer The offer of a locked episode
plugixa_stream_play_gate Hold back an episode the viewer may otherwise play; return an array to refuse
plugixa_stream_playback_source The stream handed to the player
plugixa_stream_play_response The whole unlocked answer of Play Episode
plugixa_stream_episode_array An episode’s back-office shape
plugixa_stream_user_can Whether a user may read, create, edit or delete a kind of record
plugixa_stream_rate_limit Requests per minute for each count; 0 switches it off

The plugixa_stream_register_rest_routes action fires when the plugin registers its routes. It passes the namespace and the plugin’s service container, so your routes sit beside the plugin’s:

add_action( 'plugixa_stream_register_rest_routes', function ( string $namespace ) {
	register_rest_route( $namespace, '/my-site/featured-count', array(
		'methods'             => 'GET',
		'callback'            => 'my_site_featured_count',
		'permission_callback' => function () {
			return current_user_can( 'plugixa_stream_view' );
		},
	) );
} );

See Hooks for the full set.

Troubleshooting

Symptom Usual cause
401 from a script No Application Password sent, a wrong one, or the site is not on HTTPS. Some hosts strip the Authorization header before WordPress sees it.
401 or 403 from the browser The nonce is missing or stale. Reload the page.
403 on an admin route as an editor Only administrators hold the plugin’s capabilities until you grant them to another role.
404 on a route that should exist It is a Pro route and Pro is not installed.
404 on a title or episode that exists It is a draft or scheduled, and the route is a viewer route. Use the /admin/... route.
An episode answers locked: true The caller may not play it: a paid episode the guest or viewer has not unlocked. The answer is 200, not an error.
429 on Play Episode for every guest All guests reach WordPress from one IP address, for example behind a proxy that does not pass the visitor’s address. Raise the limit with plugixa_stream_rate_limit.

See also

Quick Links

Share