REST API Reference

Endpoints and hooks marked (Pro) require MediaVerse Pro. Everything documented below ships in the free plugin.

Base URL: /wp-json/mvs/v1/

All routes below use the mvs/v1 namespace (the messaging routes share the same namespace).

Authentication. Reads of public data are open. Every write — and every /me/* route — requires an authenticated user. Pass the X-WP-Nonce header with a nonce generated via wp_create_nonce( 'wp_rest' ) and send cookies with credentials: 'same-origin', or use a WordPress Application Password for non-browser clients.

Private-community gate (2.2.0). When the host community is private, the entire mvs/v1 surface — including public reads — requires authentication, and with Pro active the mvs-pro/v1 namespace is covered by the same gate. Unauthenticated requests get 401 with code mvs_community_private. The gate is off by default and controlled by three filters: mvs_rest_require_auth (return true to arm the gate; BuddyNext arms it automatically when its private-community mode is on), mvs_rest_can_access (defaults to is_user_logged_in(); override to allow specific unauthenticated callers, e.g. a trusted server-to-server integration), and mvs_rest_gated_route_prefixes (the covered route prefixes; Pro appends its own namespace here, and sites can add more).

Authorization model. Three levels are used throughout:

Public — no auth; privacy is enforced inside the query so private rows never leak.
Authenticated — any logged-in user (is_user_logged_in()).
Capability — a specific capability such as upload_mvs_media, moderate_mvs_media, or manage_mvs_access.

Update methods. Every route documented below with PUT also accepts PATCH and POST. WordPress registers these three together as its “editable” method group, so all three reach the same handler with the same arguments and the same response. PUT is used throughout this page as the canonical form; pick whichever your HTTP client handles most comfortably.

Rate limiting. Many routes are throttled per user/IP (the limit is noted where it is unusually tight). Exceeding a limit returns 429 Too Many Requests.

Media

GET /media

Auth: Public (privacy enforced in query). Rate-limited to 120/min.

List media items. Returns only rows the caller is allowed to see.

Parameters:

Parameter	Type	Default	Description
`page`	int	`1`	Page number
`per_page`	int	`20`	Items per page (max: 100, filterable via `mvs_rest_pagination_max`)
`media_type`	string	(all)	Filter by type: `image`, `video`, `audio`, `document`
`author`	int	(all)	Filter by user ID
`slug`	string	(none)	Fetch a single item by post slug
`tag`	string	(all)	Filter by `mvs_tag` slug
`category`	string	(all)	Filter by `mvs_category` slug
`orderby`	string	`date`	Sort: `date`, `trending`, `popular` (filterable via `mvs_feed_sort_options`)
`scope`	string	`public`	`public` or `all` (owner/privileged callers)
`s`	string	(none)	Full-text search term
`group_covers`	bool	`false`	Collapse gallery groups to a single cover item

Response:

{
  "items": [
    {
      "id": 123,
      "title": "Sunset Photo",
      "description": "",
      "media_type": "image",
      "file_url": "https://example.com/wp-content/uploads/wpmediaverse/2025/03/photo.jpg",
      "privacy": "public",
      "author_id": 1,
      "album_id": null,
      "views": 42,
      "reactions_count": 5,
      "comments_count": 2,
      "created_at": "2025-03-27T12:00:00Z",
      "can_edit": false,
      "is_favorited": false,
      "viewer_reaction": null
    }
  ],
  "total": 50,
  "pages": 5
}

Viewer-aware fields. Every media item carries three fields resolved against the requesting user, not cached statically: can_edit (bool — true when the viewer is the author or has manage_options), is_favorited (bool), and viewer_reaction (string reaction slug, or null if the viewer hasn’t reacted). All three are false/null for anonymous requests. List endpoints batch-load this state per page (MediaController::prime_viewer_state()) rather than querying per row.

POST /media

Auth: Capability — upload_mvs_media (or manage_options).

Upload a new media file.

Body (multipart/form-data):

Field	Required	Description
`file`	Yes	The file to upload
`title`	No	Media title (defaults to filename)
`description`	No	Text description
`privacy`	No	Privacy level (default: site setting)
`group_id`	No	BuddyPress group ID (required when `privacy=group`)
`album_id`	No	Add to this album after upload
`is_story`	No	`true` to mark as a story

Response: 201 Created with the new media object.

GET /media/{id}

Auth: Public (privacy check in permission callback). Returns 403 if the caller cannot view it, 404 if it does not exist.

Get a single media item.

PUT /media/{id}

Auth: Capability — owner with edit_mvs_medias, or edit_others_mvs_medias.

Update a media item.

Body (JSON):

{
  "title": "Updated Title",
  "description": "Updated description",
  "privacy": "private"
}

DELETE /media/{id}

Auth: Capability — owner with delete_mvs_medias, or delete_others_mvs_medias.

Delete a media item and its stored file.

POST /media/{id}/replace

Auth: Capability — same as PUT /media/{id} (edit permission).

Replace the underlying file of an existing media item while keeping its ID, comments, reactions, and stats. Send the new file as multipart/form-data with a file field.

POST /media/{id}/view

Auth: Public.

Record a view for the item. Increments the view counter and writes a row to mvs_media_views.

POST /media/{id}/download

Auth: Public. Rate-limited to 30/min.

Record a download event and increment mvs_media_stats.downloads. Refused with 403 when the global Allow Downloads toggle is off OR the per-media allow_download meta is '0'.

POST /media/{id}/share

Auth: Public. Rate-limited to 60/min.

Record a share event and increment mvs_media_stats.shares. Called by the lightbox Share button after a successful navigator.share / clipboard copy.

GET /media/{id}/access

Auth: Public.

Report whether the current user can view the item (resolves privacy rules and any access grants). Returns an access decision, not the file.

Response:

{
  "media_id": 123,
  "can_view": true,
  "privacy": "members",
  "is_owner": false
}

privacy and is_owner are only populated when the caller can view the item or owns it; a caller with neither returns 403 before these fields are built.

GET /media/{id}/group

Auth: Public (privacy enforced per item).

Return every item that belongs to the same gallery/upload group as {id} (used to build multi-item lightboxes).

GET /media/{id}/signed-url

Auth: Authenticated with view access to the media.

Generate a time-limited signed URL for a private file. The signed URL points at /serve and carries an HMAC-SHA256 signature binding the request to a user, media ID, and expiry.

Parameter	Type	Default	Description
`download`	bool	`false`	Issue a download (attachment) URL
`ttl`	int	(setting)	Override the signed-URL lifetime, in seconds

GET /serve

Auth: Public — the HMAC signature on the URL is the credential (analogue of an S3 pre-signed URL). For non-public media the handler also re-checks can_view per request.

Stream the underlying file (full file or a thumbnail variant) for a validated signed URL. Drains output buffers and disables zlib.output_compression before streaming so byte counts match Content-Length. Honours Range: headers for video/audio.

Param	Required	Description
`mvs_id`	yes	Media ID
`mvs_uid`	yes	User ID the URL was signed for (`0` for anonymous public media)
`mvs_exp`	yes	Unix expiration timestamp
`mvs_sig`	yes	HMAC-SHA256 signature
`mvs_size`	no	`large` / `medium` / `thumbnail` / `watermark` to serve a variant
`mvs_dl`	no	When `1`, sets `Content-Disposition: attachment` and increments the download counter

GET /me/media

Auth: Authenticated.

List the current user’s own media, including private and pending items. Accepts the same parameters as GET /media.

Albums

GET /albums

Auth: Public (privacy enforced in query).

List albums. Supports page, per_page, author, orderby, order.

POST /albums

Auth: Authenticated with album-create permission.

Create an album.

{
  "title": "My Album",
  "description": "Optional",
  "privacy": "public"
}