---
title: REST API Overview
menu_group: REST API
menu_order: 1
tab: Overview
tab_order: 1
summary: MediaBlaster v3 REST namespace, discovery, schema, errors, and permissions.
---

# REST API Overview

MediaBlaster 3.0 exposes a single custom WordPress REST namespace for apps, agents, and integrations.

## Base URL

All routes live under:

```
https://YOUR-SITE.com/wp-json/mediablaster/v3
```

Legacy namespaces **`tv/roku`** and **`wpst/v1`** are not registered in 3.0.0.

## Discovery

`GET /wp-json/mediablaster/v3`

Public. Returns API metadata and links to major endpoints.

Example response fields:

| Field | Description |
|-------|-------------|
| `name` | Product name (MediaBlaster) |
| `version` | Plugin version |
| `namespace` | `mediablaster/v3` |
| `enabled_post_types` | Active content types on this site |
| `features` | `vimeo`, `subscriptions`, `agent_tools` flags |
| `links` | Absolute URLs to schema, content, type routes, Vimeo, auth |

Use this endpoint to probe capabilities before building a client.

## Schema

Describe the public field model (not raw WordPress meta keys).

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/schema` | Schema for all supported types |
| GET | `/schema/{type}` | Schema for one type (`movies`, `videos`, `episodes`, `series`) |

Each schema object includes `type`, `label`, `supports`, and a `fields` map with types, enums, and required flags.

See [Content API and Fields](rest-api-content.md) for how schema fields map to request and response bodies.

## Error responses

Errors use WordPress `WP_Error` JSON:

```json
{
  "code": "mediablaster_not_found",
  "message": "Content not found.",
  "data": { "status": 404 }
}
```

Common codes:

| Code | HTTP | Meaning |
|------|------|---------|
| `mediablaster_invalid_type` | 400 | Unknown or disallowed post type |
| `mediablaster_invalid_payload` | 400 | Validation failed |
| `mediablaster_not_found` | 404 | Post missing or wrong type for route |
| `mediablaster_forbidden` | 403 | Capability or publish permission denied |
| `mediablaster_vimeo_not_configured` | 400 | Vimeo integration off or not connected |
| `mediablaster_vimeo_sync_failed` | 500 | Vimeo API or sync error |

## Permissions (summary)

| Action | Requirement |
|--------|-------------|
| Read published content | Public (subject to subscription access rules) |
| Read drafts/private | User with `edit_posts` and appropriate query |
| Create content | `edit_posts` |
| Update content | `edit_post` on that post |
| Delete / trash | `delete_post`; permanent delete needs `force=true` and strong delete cap |
| Vimeo import/sync | `edit_posts` + Vimeo enabled |
| Admin stats | `manage_options` |
| Auth / payments | See [Subscriptions and Apps API](rest-api-subscriptions.md) |

Locked premium content may omit `media.url` for users without access while other metadata remains visible.

## Endpoint index

### Content (always available)

| Method | Route |
|--------|-------|
| GET, POST | `/content` |
| GET, PATCH, DELETE | `/content/{id}` |
| GET, POST | `/movies`, `/videos`, `/episodes`, `/series` |
| GET, PATCH, DELETE | `/{type}/{id}` |

Type routes are aliases of `/content` with `type` implied by the path.

### Vimeo (requires **Enable Vimeo Integration**)

| Method | Route |
|--------|-------|
| GET | `/vimeo/status` |
| POST | `/vimeo/import` |
| POST | `/vimeo/sync/{post_id}` |

See [Vimeo REST API](rest-api-vimeo.md).

### Subscriptions and apps (requires `WPST_SUBSCRIPTIONS_ENABLED` + REST enabled)

| Method | Route |
|--------|-------|
| GET | `/me` |
| GET | `/subscription/status` |
| GET | `/subscription/tiers` |
| GET | `/app/config` |
| POST | `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh` |
| POST | `/payments/stripe/create-checkout-session` |
| POST | `/payments/stripe/create-portal-session` |
| GET | `/payments/stripe/checkout-session` |
| POST | `/payments/stripe/webhook` (and other provider webhooks) |
| GET | `/stats/content`, `/stats/subscriptions`, `/stats/revenue` |

See [Subscriptions and Apps API](rest-api-subscriptions.md).

## Authentication for write requests

- **WordPress session** — cookie auth while logged into wp-admin works for same-origin tools.
- **Application Passwords** — standard WordPress application passwords for server-to-server writes.
- **Bearer tokens** — when subscriptions REST is enabled, `POST /auth/login` returns a token; send `Authorization: Bearer {token}` on subsequent requests.

## Related guides

- [Content API and Fields](rest-api-content.md)
- [Vimeo REST API](rest-api-vimeo.md)
- [Subscriptions and Apps API](rest-api-subscriptions.md)
- [Subscriptions API and Auth](subscriptions-api-auth.md) (admin settings)
- [Import and Export](import-export.md)