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.
Cookie and nonce
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
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
- How episodes become free or locked: Free and locked episodes.
- Coins, unlocks and VIP from the viewer’s side: Coins and unlocks PRO.
- The CSV format in detail: Import and export.
- Change behaviour in PHP instead: Hooks.
Quick Links
Share