---
title: REST API — Search
menu_group: REST API
menu_order: 12
tab: REST API
tab_order: 12
summary: Unified search across video content and podcast shows via GET /search.
---

# REST API — Search

Namespace: `/wp-json/mediablaster/v3`

`GET /search` provides a single entry point for app Search screens. Results may include video content (movies, videos, series, episodes) and podcast shows in one paginated list. Use the `type` field on each item to render the correct card or navigation target.

## Endpoint

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/search` | Unified search (required `search` param) |

Public read. Discovery index includes `links.search`.

## Query parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `search` | Yes | — | Search string (WordPress `s` — title, content, excerpt) |
| `page` | No | `1` | Page number |
| `per_page` | No | `20` | Items per page (max `100`) |
| `types` | No | all enabled | Comma-separated filter: `movies`, `videos`, `series`, `episodes`, `podcast_show`, `podcast_episode` |
| `include_podcast_episodes` | No | `false` | When `true` and podcasts are enabled, include matching podcast episodes |

Missing or empty `search` returns **400** `mediablaster_search_required`.

## Response

```json
{
  "items": [
    {
      "id": 12,
      "type": "movies",
      "title": "Action Movie",
      "thumbnail": { "url": "https://example.com/thumb.jpg" }
    },
    {
      "id": 4,
      "type": "podcast_show",
      "title": "History Podcast",
      "artwork": "https://example.com/art.jpg"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}
```

### Item `type` values

| `type` | Source | Shape |
|--------|--------|-------|
| `movies`, `videos`, `series`, `episodes` | Content API serializer | Same as [Content API](rest-api-content.md) list items |
| `podcast_show` | Podcast tools | Same as `GET /podcasts` show objects |
| `podcast_episode` | Podcast tools | Same as episode objects (only when `include_podcast_episodes=true`) |

Results are merged and sorted by publish date (newest first).

## Examples

```
GET /wp-json/mediablaster/v3/search?search=action&page=1&per_page=20
GET /wp-json/mediablaster/v3/search?search=history&types=movies,podcast_show
GET /wp-json/mediablaster/v3/search?search=episode&include_podcast_episodes=true
```

## Podcast show list search

To search **shows only** with the existing podcast list format (bare array + `X-WP-Total` headers):

```
GET /wp-json/mediablaster/v3/podcasts?search=history&page=1&per_page=20
```

See [REST API — Podcasts](rest-api-podcasts.md).

## Content list search (per-type)

Individual content routes still support `?search=` with the `{ items, pagination }` envelope:

```
GET /wp-json/mediablaster/v3/content?search=action
GET /wp-json/mediablaster/v3/movies?search=action
```

Use `/search` when the client needs **mixed** video + podcast results in one request.

## Feature gating

- Video types follow `enabled_post_types` on the discovery index.
- Podcast shows and episodes are included only when **Enable Podcasts** is on.
- Subscription `hide_completely` video items are excluded from search the same way as content collections.

## Related

- [Content API and Fields](rest-api-content.md)
- [REST API — Podcasts](rest-api-podcasts.md)
- [REST API Overview](rest-api-overview.md)