---
title: Categories API
menu_group: REST API
menu_order: 15
tab: Content
tab_order: 15
summary: Paginated category list for Roku category pickers and content filtering.
---

# Categories API

`GET /wp-json/mediablaster/v3/categories` returns browse categories for connected clients. Categories are sourced from Roku Direct Publisher category recipes when configured; otherwise the API falls back to the plugin genre list.

## Endpoint

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/categories` | Paginated category list |

Public read. No authentication required.

## Query parameters

| Parameter | Description |
|-----------|-------------|
| `page` | Page number (default `1`) |
| `per_page` | Items per page (default `20`, max `100`) |

## Response

```json
{
  "items": [
    {
      "id": 1,
      "name": "Featured",
      "type": "recipe",
      "query": "Featured",
      "order": "date"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}
```

### Item fields

| Field | Description |
|-------|-------------|
| `id` | Stable numeric ID for `GET /content?category={id}` |
| `name` | Display label for the category picker |
| `type` | `recipe` (Roku tag recipe), `playlist`, or `genre` (fallback) |
| `query` | Tag query string, playlist series ID, or genre slug |
| `order` | Suggested sort from recipe settings (may be empty for genres) |

## Filter content by category

Use the category `id` from this list on the content API:

```
GET /wp-json/mediablaster/v3/content?category=1&page=1&per_page=20
```

Filtering behavior:

| `type` | Effect on `/content` |
|--------|----------------------|
| `recipe` | Filters by WordPress post tag (`query`) |
| `playlist` | Limits to episodes in the series playlist (`rovidx_smarttv_playlist`) |
| `genre` | Filters by genre meta (`rovidx_smarttv_genres`) |

The `genre` query parameter on `/content` still works independently and filters by genre slug directly.

## Data sources

1. **Primary:** `wpstv_rdp` option, field `rovidx_smart_tv_category_recipe` (same recipes used for the internal Roku JSON feed).
2. **Fallback:** Genre list from **MediaBlaster** settings when no recipes are configured.

## Related

- [Content API and Fields](rest-api-content.md) — list pagination and tag-scan behavior
- [REST API Overview](rest-api-overview.md)