REST API Reference
MediaShield overviewFree + ProGet MediaShield →
Included in Free - 25 routes in mediashield/v1, plus the core wp/v2 routes for the two post types. Pro’s own namespace, mediashield-pro/v1, is documented in the Pro developer guide.
Free plugin - mediashield/v1
Section titled “Free plugin - mediashield/v1”Base URL: /wp-json/mediashield/v1/
Authentication: standard WordPress REST API nonce via the X-WP-Nonce header, or cookie-based auth. There is no single capability for the whole namespace - each group states its own below, and they range from “administrator” to “anyone with a valid nonce”.
Settings
Section titled “Settings”| Method | Route | Auth | Description |
|---|---|---|---|
| GET | /settings |
manage_options | Retrieve all settings. Output filtered via mediashield_settings_response. |
| PUT | /settings |
manage_options | Update settings. Partial updates supported. Unknown keys are ignored. |
PUT behavior: known keys are type-cast to their schema type, then run through that key’s validator. A value that fails validation (an invalid hex color, a protection level outside the allowed set, a malformed URL) is skipped and the previously stored value is kept. Numeric ranges are clamped rather than rejected - opacity to 0-1, retention months to 0-120, ad skip delay to 0-60.
| Method | Route | Auth | Description |
|---|---|---|---|
| GET | /tags |
logged in | List tags. Args: page, per_page (max 100, default 50), search. |
| POST | /tags |
edit_posts | Create a tag. Body: { name, description? }. The slug is derived from the name. |
| GET | /tags/{id} |
logged in | Get a single tag. |
| PATCH | /tags/{id} |
edit_posts | Update name and/or description. Note: PATCH, not PUT. |
| DELETE | /tags/{id} |
edit_posts | Delete a tag and remove all video-tag associations for it. Returns 204. |
| GET | /videos/{video_id}/tags |
logged in | Tags assigned to a video. |
| POST | /videos/{video_id}/tags |
edit_posts | Assign a tag to a video. Body: { tag_id }. |
| DELETE | /videos/{video_id}/tags/{tag_id} |
edit_posts | Remove a tag from a video. |
Sessions
Section titled “Sessions”| Method | Route | Auth | Description |
|---|---|---|---|
| POST | /session/start |
logged in, or anonymous when allowed | Start a watch session. Body: { video_id }. Returns the session token, resume position, watermark config, and video details. |
| POST | /session/heartbeat |
logged in, or a valid session token | Update progress. Body: { token, position, duration, playing?, focused? }. token, position and duration are required; playing and focused default to true. |
| POST | /session/end |
logged in, or a valid session token | End session and finalize stats. Body: { token }. |
| POST | /session/revoke-user |
manage_options | End all active sessions for a user. Body: { user_id }. |
Anonymous access to /session/start is allowed when the ms_require_login setting is off, when the video carries an _ms_access_type meta value, or when an integration admits guests to that video through the mediashield_guest_can_watch filter (Learnomy does this for free-preview lessons), and can be adjusted with the mediashield_session_allow_anonymous_start filter. Reaching the handler is not permission to watch: AccessControl::can_watch() still runs and can refuse with a reason.
Heartbeat and end accept a signed token instead of a login, because a guest who was allowed to start a session must be able to finish it. The token is HMAC-signed and validated without a database lookup; anything unsigned or tampered with is rejected.
The parameter is named token, not session_token. Heartbeat interval is 30 seconds. A session with no heartbeat for 5 minutes stops counting toward the concurrent-stream limit, and an hourly job marks sessions inactive after 10 minutes.
Starting a session beyond the concurrent limit returns HTTP 429 with code concurrent_limit. Heartbeats are also rate limited: more than 4 requests in 60 seconds from one session returns 429 rate_limited.
Stream
Section titled “Stream”| Method | Route | Auth | Description |
|---|---|---|---|
| GET | /stream/{video_id} |
mediashield_can_watch for the resolved viewer |
Streams a self-hosted video file with range support. |
| GET | /stream/{video_id}/url |
mediashield_can_watch for the logged-in viewer |
Returns { "url": ... }, a freshly signed stream URL. The player asks for it once when the URL printed in the page has expired (cached page, long-open tab, changed salts) and resumes from where it stopped. |
This endpoint serves the file itself; it does not redirect to one. It runs the same access check as the player on every request, including every range request, so access revoked mid-playback is refused on the next seek. Files inside uploads/mediashield/ are served only to the video recorded as their owner (_ms_owned_file), so one video’s URL cannot be pointed at another video’s file.
A <video> element cannot send an X-WP-Nonce header, so the player appends a signed ms_token query parameter naming the viewer the URL was minted for. The token is identity, not authorisation - the access check still runs for that viewer. Stream tokens are valid for 6 hours.
Playlists
Section titled “Playlists”| Method | Route | Auth | Description |
|---|---|---|---|
| GET | /playlists/{playlist_id}/player/{video_id} |
public | The protected player markup (html) for one video in a playlist. Used by the playlist page when the viewer moves to another video. 404 unless the video is in that playlist, both are published, and the playlist is not password protected. Who may watch is still decided by /session/start and /stream. |
| GET | /playlists/{playlist_id}/items |
logged in | List items in a playlist in sort order. |
| POST | /playlists/{playlist_id}/items |
edit_posts | Add a video to a playlist. Body: { video_id, sort_order? }. |
| DELETE | /playlists/{playlist_id}/items/{item_id} |
edit_posts | Remove a video from a playlist. |
| PUT | /playlists/{playlist_id}/items/reorder |
edit_posts | Reorder items. Body: { order: [ { item_id, sort_order }, ... ] }. |
Note the reorder route is PUT and takes objects, not a flat list of IDs.
Playlist playback options (_ms_autoplay, _ms_countdown, _ms_loop, _ms_shuffle) are post meta and are read and written through the WordPress core route for the CPT, /wp/v2/mediashield-playlists/{id}.
Upload
Section titled “Upload”| Method | Route | Auth | Description |
|---|---|---|---|
| POST | /upload/init |
upload_mediashield | Upload a video file. |
| GET | /upload/status/{upload_id} |
upload_mediashield | Ask a driver about an upload. Args: driver (default self_hosted). Returns { status, progress, error }. |
/upload/init takes a multipart form POST with the file in a field named file, plus optional title, driver (default self_hosted), and video_id. It is a single request; there is no chunking and no separate initialization step.
Passing video_id attaches the file to an existing video instead of creating a new one, which is what the admin uploader does. That path additionally requires edit_post on the target video: upload_mediashield says you may upload, not that you may overwrite any video on the site by ID.
On success it returns 201 with { video_id, platform_video_id, embed_url, status: "complete" }. Failures return 400 (no file, or a PHP upload error), 404 (unknown video_id), 403 (cannot edit that video), or 422 (the driver refused the file).
The upload_mediashield capability is separate from manage_options so instructors or content managers can upload videos without full admin access. Activation grants it to Administrator only.
Analytics
Section titled “Analytics”| Method | Route | Auth | Description |
|---|---|---|---|
| GET | /analytics/overview |
manage_options | Dashboard summary. Arg: period = today | 7d (default) | 30d | 90d. Returns total videos, sessions, avg completion, active viewers, activity chart, top videos, recent milestones, and the site timezone. Daily counts use CONVERT_TZ() to respect the WP site timezone. |
| GET | /videos/{id}/stats |
manage_options | Per-video statistics. |
| GET | /analytics/milestones |
manage_options | Milestone log. Args: page, per_page (default 20), video_id. Total counts come back in the X-WP-Total and X-WP-TotalPages headers. |
| GET | /analytics/users |
manage_options | Viewer list. Args: page, per_page (default 20), search. |
| GET | /analytics/users/{user_id} |
manage_options | One viewer’s sessions, newest first, paged (page, per_page up to 100, default 20; total, total_pages and videos_watched in the body, X-WP-Total / X-WP-TotalPages headers), with video title, completion, watch time, furthest position, and timestamps. Milestone history, IP, and device type are not included in this payload. |
| GET | /analytics/my-videos |
logged in | Current user’s watched videos. No admin capability required. |
period values other than the four listed fall back to 7 days. “Today” means the last 24 hours, not the calendar day.
Protection
Section titled “Protection”| Method | Route | Auth | Description |
|---|---|---|---|
| POST | /protection/devtools-event |
valid wp_rest nonce (guests allowed) |
Beacon endpoint for client-side devtools detection. Args: strategy, url, ua, screen. Responds { recorded: true } and fires mediashield_devtools_detected; free does not log it or store it. strategy is required and must be size_delta or debugger_timing; the player sends only debugger_timing since 1.4.2. |
Rate limited to one recorded event per user and IP per hour. A limited request still returns 200 with { recorded: false, reason: "rate_limited" }.
Wizard
Section titled “Wizard”| Method | Route | Auth | Description |
|---|---|---|---|
| POST | /wizard/complete |
manage_options | Mark the setup wizard as complete. |
Core routes for the custom post types
Section titled “Core routes for the custom post types”Videos and playlists are custom post types with show_in_rest enabled, so the standard WordPress routes apply and are where you create, update, and delete them:
/wp/v2/mediashield-videosand/wp/v2/mediashield-videos/{id}/wp/v2/mediashield-playlistsand/wp/v2/mediashield-playlists/{id}
Video and playlist meta (_ms_platform, _ms_source_url, _ms_protection_level, _ms_duration, the player overrides, the playlist playback options) is registered with show_in_rest, so it round-trips through the meta object on those routes. This is how the block editor creates a video from a pasted URL.
Who sees the video meta (since 1.4.2): the addresses that lead to the media (_ms_source_url, _ms_platform_video_id, _ms_stream_url) are returned only to people who can edit that video (edit_post). People who can write posts but not edit this video get the other meta, which the Video block picker shows. Visitors and members get no meta at all. This holds for every response shape, including _fields, context=edit, _embed and list requests. Writing any video meta needs edit_post on that video. The playlist items route (GET /playlists/{id}/items) applies the same rule to each item’s source_url. Player markup never carries a self-hosted video’s stored file name (data-platform-video-id is empty for self) or a direct URL into uploads/mediashield/; playback uses the signed /stream/{id} URL.
A Media Library file that a self-hosted video plays from is moved into uploads/mediashield/ and its Media Library item becomes private (see Background Jobs and WP-CLI), so /wp/v2/media no longer lists it for anyone who cannot read private media.

