Skip to content

REST API Reference

CastConductor provides a REST API for retrieving channel content.

Base URL

https://yoursite.com/wp-json/castconductor/v5/

Authentication

Most read endpoints are public. Write operations require authentication via:

  • License Key: Header X-CastConductor-License
  • WordPress Nonce: For authenticated WordPress users

Endpoints

Content Blocks

List Content Blocks

GET /wp-json/castconductor/v5/content-blocks

Parameters:

Param Type Description
type string Filter by content type
per_page int Items per page (default: 20)
page int Page number

Response:

{
  "blocks": [
    {
      "id": 123,
      "title": "Featured Video",
      "type": "video",
      "url": "https://example.com/video.mp4",
      "thumbnail": "https://example.com/thumb.jpg",
      "metadata": {}
    }
  ],
  "total": 50,
  "pages": 3
}

Get Single Block

GET /wp-json/castconductor/v5/content-blocks/{id}

Scenes

List Scenes

GET /wp-json/castconductor/v5/scenes

Get Scene

GET /wp-json/castconductor/v5/scenes/{id}

Response:

{
  "id": 1,
  "name": "Home",
  "layout": {
    "elements": [
      {
        "blockId": 123,
        "x": 100,
        "y": 50,
        "width": 400,
        "height": 225
      }
    ]
  },
  "navigation": {}
}

Containers

List Containers

GET /wp-json/castconductor/v5/containers

Get Container

GET /wp-json/castconductor/v5/containers/{id}

App Configuration

Get App Config

GET /wp-json/castconductor/v5/app-config

Returns the complete app configuration for Roku.

Error Handling

All errors return standard HTTP status codes:

Code Meaning
200 Success
400 Bad Request
401 Unauthorized
404 Not Found
500 Server Error

Error Response:

{
  "code": "invalid_param",
  "message": "Invalid content block ID",
  "data": {
    "status": 400
  }
}

Rate Limiting

API requests are rate-limited to prevent abuse:

  • 100 requests/minute per IP
  • 1000 requests/hour per license

Examples

cURL

curl -X GET "https://yoursite.com/wp-json/castconductor/v5/content-blocks" \
  -H "Accept: application/json"

JavaScript

const response = await fetch(
  'https://yoursite.com/wp-json/castconductor/v5/content-blocks'
);
const data = await response.json();