API docs by Redocly

EncoraStream CMS API (2.0.0)

Download OpenAPI specification:

EncoraStream API Team: api-support@encorastream.com License: Proprietary

Content Management System and content delivery endpoints for the EncoraStream OTT Platform.

Covers:

  • Public content catalogue: Movies, Shows, Episodes, Live TV, EPG, Collections, Genres
  • Full-text search and autocomplete
  • Admin content authoring: CRUD, publish/unpublish, media ingest
  • EPG management and bulk import
  • Genre and collection management
  • Geo-restriction rules
  • Webhooks and delivery logs
  • Analytics and audit logs
  • Playback: stream URLs, DRM licence acquisition, heartbeat
  • Watchlist, watch history, ratings, downloads, reminders, DVR recordings
  • Device registration and management
  • System health, config, and version

Movies

Movie catalogue (read-only)

List Movies

Returns published movies available to the authenticated user's territory and subscription.

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

q
string <= 200 characters

Full-text search query (max 200 characters).

genre
string
release_year
integer
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"
language
string
fields
string

Comma-separated list of fields to include in the response (sparse fieldset). Example: fields=id,title,images. Omit for the full representation.

header Parameters
If-None-Match
string

ETag from a prior response. Returns 304 Not Modified if the resource is unchanged.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Movie

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
query Parameters
fields
string

Comma-separated list of fields to include in the response (sparse fieldset). Example: fields=id,title,images. Omit for the full representation.

header Parameters
If-None-Match
string

ETag from a prior response. Returns 304 Not Modified if the resource is unchanged.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Movie Trailers

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Related Movies

Returns movies similar to the specified title based on genre, cast, and viewing patterns.

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Movie Stream URLs

Returns short-lived signed DASH/HLS manifest URLs. Requires an active subscription that covers this title. Device ID header is required and validated against registered devices. Concurrency is enforced against the plan's max_concurrent_streams limit.

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

Responses

Response samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "dash_url": "http://example.com",
  • "hls_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token_refresh_before": "2019-08-24T14:15:22Z"
}

Get Movie Subtitle & Audio Tracks

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "subtitles": [
    ],
  • "audio": [
    ]
}

Shows

TV show catalogue (read-only)

List Shows

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

q
string <= 200 characters

Full-text search query (max 200 characters).

genre
string
status
string
Enum: "ongoing" "ended" "canceled"
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Show

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Seasons for a Show

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{}

Get a Specific Season

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1

Responses

Response samples

Content type
application/json
{}

List Show Trailers

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Related Shows

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Episodes

Episode listing and stream tracks

List Episodes in a Season

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Episode

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
episode_number
required
integer >= 0

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "show_id": "503c9125-a11a-4f69-b904-e679735399e2",
  • "season_id": "3e93eb58-18e4-4960-a483-d51daf6cd6fd",
  • "season_number": 1,
  • "episode_number": 0,
  • "title": "string",
  • "synopsis": "string",
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "images": {},
  • "status": "draft",
  • "air_date": "2019-08-24",
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Episode Stream URLs

Same concurrency, geo, and subscription enforcement as movie streaming.

Authorizations:
OAuth2PKCE
path Parameters
episode_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

Responses

Response samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "dash_url": "http://example.com",
  • "hls_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token_refresh_before": "2019-08-24T14:15:22Z"
}

Get Episode Subtitle & Audio Tracks

Authorizations:
OAuth2PKCE
path Parameters
episode_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "subtitles": [
    ],
  • "audio": [
    ]
}

LiveTV

Live TV channel listing and streaming

List Live TV Channels

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

q
string <= 200 characters

Full-text search query (max 200 characters).

category
string
language
string
status
string
Enum: "live" "offline"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Channel

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Live Channel Stream URLs

Returns short-lived signed DASH/HLS manifest URLs for a live channel. Validates subscription, geo, device registration, and concurrency.

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

Responses

Response samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "dash_url": "http://example.com",
  • "hls_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token_refresh_before": "2019-08-24T14:15:22Z"
}

Get Catch-Up Stream for a Past Programme

Returns stream URLs for a previously aired programme (time-shifted replay).

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
query Parameters
program_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

Responses

Response samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "dash_url": "http://example.com",
  • "hls_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token_refresh_before": "2019-08-24T14:15:22Z"
}

Start Over Current Programme

Restarts the currently-airing programme from the beginning (start-over).

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

Responses

Response samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "dash_url": "http://example.com",
  • "hls_url": "http://example.com",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token_refresh_before": "2019-08-24T14:15:22Z"
}

EPG

Electronic Programme Guide

Get EPG Schedule

Returns programme schedule for one or more channels within a time range. Maximum time window: 7 days.

Authorizations:
OAuth2PKCE
query Parameters
channel_ids
required
Array of strings <uuid> [ 1 .. 50 ] items [ items <uuid > ]
start_time
required
string <date-time>
end_time
required
string <date-time>
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

What's On Now

Returns the currently-airing programme for each requested channel.

Authorizations:
OAuth2PKCE
query Parameters
channel_ids
required
Array of strings <uuid> [ 1 .. 50 ] items [ items <uuid > ]

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get EPG Program Details

Authorizations:
OAuth2PKCE
path Parameters
program_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "title": "string",
  • "description": "string",
  • "content_rating": "G",
  • "language": "en",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "duration_minutes": 0,
  • "is_live": true,
  • "is_catchup_available": true,
  • "catchup_expires_at": "2019-08-24T14:15:22Z",
  • "season_number": 0,
  • "episode_number": 0,
  • "categories": [
    ],
  • "images": {},
  • "linked_vod_id": "657aaad7-6df0-4878-8900-295f294bc20e"
}

Collections

Curated collections and server-driven home layout

List Collections

Returns published collections. Geo-filtered by caller region.

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Collection and its Items

Authorizations:
OAuth2PKCE
path Parameters
collection_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "item_count": 0,
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Home Screen Layout

Returns the server-driven home screen layout — an ordered list of rails. Supports If-None-Match for efficient polling (returns 304 when unchanged).

Authorizations:
OAuth2PKCE
header Parameters
X-Profile-Id
string <uuid>

Active sub-profile ID for multi-profile accounts.

If-None-Match
string

ETag from a prior response. Returns 304 Not Modified if the resource is unchanged.

Responses

Response samples

Content type
application/json
{}

Genres

Content genre taxonomy

List Content Genres

Returns the full genre taxonomy. Cacheable — changes infrequently.

Authorizations:
OAuth2PKCE
query Parameters
content_type
string
Enum: "movie" "show"
header Parameters
If-None-Match
string

ETag from a prior response. Returns 304 Not Modified if the resource is unchanged.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Search

Full-text search and autocomplete

Full-Text Search

Searches across movies, shows, episodes, and channels. Results are geo-filtered and subscription-aware. Only published and scheduled content appears.

Authorizations:
OAuth2PKCE
query Parameters
q
string <= 200 characters

Full-text search query (max 200 characters).

cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

content_type
string
Enum: "movie" "show" "episode" "channel"
genre
string
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"
release_year_min
integer >= 1888
release_year_max
integer <= 2100
language
string

Responses

Response samples

Content type
application/json
{
  • "data": [],
  • "meta": {
    }
}

Search Autocomplete

Returns type-ahead suggestions as the user types. Results are lightweight (title + type only).

Authorizations:
OAuth2PKCE
query Parameters
q
required
string [ 1 .. 100 ] characters
limit
integer [ 1 .. 20 ]
Default: 10

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

System

App bootstrap configuration, health, and version

Get App Bootstrap Configuration

Returns client configuration fetched on app launch: feature flags, minimum app versions, CDN base URL, and maintenance status. Supports If-None-Match for efficient polling.

query Parameters
platform
required
string
Enum: "ios" "android" "tvos" "web" "roku" "firetv"
header Parameters
If-None-Match
string

ETag from a prior response. Returns 304 Not Modified if the resource is unchanged.

Responses

Response samples

Content type
application/json
{
  • "minimum_app_version": {
    },
  • "feature_flags": {
    },
  • "cdn_base_url": "http://example.com",
  • "maintenance": {
    },
  • "supported_locales": [
    ],
  • "config_version": "string"
}

Health Check

Returns overall platform health and per-component status. Does not require authentication. Used by load balancers and monitoring systems. Returns 200 for ok and degraded; returns 503 for down.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "2.0.0",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "components": {
    }
}

Readiness Check

Kubernetes-style readiness probe. Returns 200 when all critical dependencies (database, cache, DRM) are available. Returns 503 otherwise. Use for traffic routing decisions (not for end-user display).

Responses

Get API Version

Returns the deployed API and service versions. Use for client-side compatibility checks.

Responses

Response samples

Content type
application/json
{
  • "api_version": "2.0.0",
  • "build_date": "2019-08-24",
  • "commit_sha": "string"
}

Movies (Admin)

Movie authoring, publishing, and unpublishing

List Movies (Admin)

Returns all movies including drafts, unpublished, and scheduled. Geo-unfiltered.

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

q
string <= 200 characters

Full-text search query (max 200 characters).

status
string
Enum: "draft" "published" "scheduled" "unpublished"
genre
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Movie (Admin)

Authorizations:
OAuth2PKCE
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended — time-ordered, collision-resistant) that makes a write request safely retryable. Replaying the same key within 24h returns the original result instead of performing the action twice. Strongly recommended on all payment and subscription mutations.

Request Body schema: application/json
required
title
required
string <= 255 characters
original_title
string <= 255 characters

Original title if different from localised title.

synopsis
string <= 5000 characters
tagline
string <= 300 characters
release_year
integer [ 1888 .. 2100 ]
runtime_minutes
integer >= 1

Total runtime. Required before publishing.

content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Parental guidance rating. Required before publishing.

genres
Array of strings

Genre slugs (from /genres taxonomy).

country_of_origin
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 production country codes.

studio
string <= 200 characters

Primary production studio or distributor.

audio_languages
Array of strings

BCP-47 language codes for available dubbed/original audio tracks.

subtitle_languages
Array of strings

BCP-47 language codes for available subtitle/CC tracks.

Array of objects (CastMember)
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "scheduled" "unpublished"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean

When true, clients must acquire a DRM licence before playback.

available_from
string <date-time>

Earliest playback availability datetime (window start).

available_until
string <date-time>

Last playback availability datetime (window end). Null = indefinite.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "original_title": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Movie (Admin)

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Movie (Admin)

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
title
required
string <= 255 characters
original_title
string <= 255 characters

Original title if different from localised title.

synopsis
string <= 5000 characters
tagline
string <= 300 characters
release_year
integer [ 1888 .. 2100 ]
runtime_minutes
integer >= 1

Total runtime. Required before publishing.

content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Parental guidance rating. Required before publishing.

genres
Array of strings

Genre slugs (from /genres taxonomy).

country_of_origin
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 production country codes.

studio
string <= 200 characters

Primary production studio or distributor.

audio_languages
Array of strings

BCP-47 language codes for available dubbed/original audio tracks.

subtitle_languages
Array of strings

BCP-47 language codes for available subtitle/CC tracks.

Array of objects (CastMember)
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "scheduled" "unpublished"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean

When true, clients must acquire a DRM licence before playback.

available_from
string <date-time>

Earliest playback availability datetime (window start).

available_until
string <date-time>

Last playback availability datetime (window end). Null = indefinite.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "original_title": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Movie (Admin)

Permanently deletes a movie. Only permitted when status is draft or unpublished.

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Publish Movie

Transitions movie from draft or unpublished to published. Validates that required fields (runtime, content_rating, at least one video asset) are present.

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
optional
available_from
string <date-time>

Schedule publication for a future datetime. Omit for immediate publication.

Responses

Request samples

Content type
application/json
{
  • "available_from": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Unpublish Movie

Moves movie from published to unpublished. Immediately removes the title from subscriber catalogue. Active streams are allowed to finish but no new streams can be started.

Authorizations:
OAuth2PKCE
path Parameters
movie_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "tagline": "string",
  • "release_year": 1888,
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "genres": [
    ],
  • "country_of_origin": [
    ],
  • "studio": "string",
  • "audio_languages": [
    ],
  • "subtitle_languages": [
    ],
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Shows (Admin)

Show authoring, publishing, and unpublishing

List Shows (Admin)

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

q
string <= 200 characters

Full-text search query (max 200 characters).

status
string
Enum: "draft" "published" "ongoing" "ended" "canceled"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Show (Admin)

Authorizations:
OAuth2PKCE
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended — time-ordered, collision-resistant) that makes a write request safely retryable. Replaying the same key within 24h returns the original result instead of performing the action twice. Strongly recommended on all payment and subscription mutations.

Request Body schema: application/json
required
title
required
string <= 255 characters
original_title
string <= 255 characters
synopsis
string <= 5000 characters
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Parental guidance rating. Required before publishing.

genres
Array of strings

Genre slugs (from /genres taxonomy).

network
string <= 200 characters

Original broadcaster or streaming network (e.g. HBO, Netflix).

country_of_origin
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 production country codes.

language
string

Primary audio language (BCP-47).

first_air_date
string <date>

Date the first episode aired.

last_air_date
string <date>

Date the most recent episode aired.

Array of objects (CastMember)
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "ongoing" "ended" "canceled"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "original_title": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "cast": [
    ],
  • "images": {},
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Show (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Show (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
title
required
string <= 255 characters
original_title
string <= 255 characters
synopsis
string <= 5000 characters
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Parental guidance rating. Required before publishing.

genres
Array of strings

Genre slugs (from /genres taxonomy).

network
string <= 200 characters

Original broadcaster or streaming network (e.g. HBO, Netflix).

country_of_origin
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 production country codes.

language
string

Primary audio language (BCP-47).

first_air_date
string <date>

Date the first episode aired.

last_air_date
string <date>

Date the most recent episode aired.

Array of objects (CastMember)
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "ongoing" "ended" "canceled"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "original_title": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "cast": [
    ],
  • "images": {},
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Show (Admin)

Permanently deletes a show and all its seasons/episodes. Only permitted when status is draft.

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Publish Show

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Unpublish Show

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "original_title": "string",
  • "slug": "string",
  • "synopsis": "string",
  • "content_rating": "G",
  • "genres": [
    ],
  • "network": "string",
  • "country_of_origin": [
    ],
  • "language": "en",
  • "first_air_date": "2019-08-24",
  • "last_air_date": "2019-08-24",
  • "total_seasons": 0,
  • "total_episodes": 0,
  • "cast": [
    ],
  • "images": {},
  • "average_rating": 5,
  • "rating_count": 0,
  • "status": "draft",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Seasons (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{}

Create Season (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
Request Body schema: application/json
required
season_number
required
integer >= 1
title
string <= 255 characters

Optional explicit season title (e.g. "Chapter One"). Null = "Season {N}" by default.

synopsis
string <= 2000 characters
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

air_date
string <date>

Date the first episode of this season aired.

end_date
string <date>

Date the final episode aired (null if season is ongoing).

status
required
string
Enum: "draft" "published" "completed"

completed = all episodes aired and available; published = actively airing; draft = not yet visible to subscribers.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get Season (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1

Responses

Response samples

Content type
application/json
{}

Update Season (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
season_number
required
integer >= 1
title
string <= 255 characters

Optional explicit season title (e.g. "Chapter One"). Null = "Season {N}" by default.

synopsis
string <= 2000 characters
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

air_date
string <date>

Date the first episode of this season aired.

end_date
string <date>

Date the final episode aired (null if season is ongoing).

status
required
string
Enum: "draft" "published" "completed"

completed = all episodes aired and available; published = actively airing; draft = not yet visible to subscribers.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete Season (Admin)

Soft-deletes the season and all its episodes. Only permitted when none of the season's episodes have been published. Audit-logged.

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Episodes (Admin)

Episode authoring within seasons

List Episodes (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Episode (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
Request Body schema: application/json
required
season_number
required
integer >= 1
episode_number
required
integer >= 0

0 indicates a special/bonus episode.

title
required
string <= 255 characters
synopsis
string <= 2000 characters
runtime_minutes
integer >= 1

Runtime in minutes. Required before publishing.

content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Inherits from show if not set; must be set before publishing.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "scheduled" "unpublished"
air_date
string <date>

Original broadcast air date.

available_from
string <date-time>
available_until
string <date-time>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "show_id": "503c9125-a11a-4f69-b904-e679735399e2",
  • "season_id": "3e93eb58-18e4-4960-a483-d51daf6cd6fd",
  • "season_number": 1,
  • "episode_number": 0,
  • "title": "string",
  • "synopsis": "string",
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "images": {},
  • "status": "draft",
  • "air_date": "2019-08-24",
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Episode (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
episode_number
required
integer >= 0

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "show_id": "503c9125-a11a-4f69-b904-e679735399e2",
  • "season_id": "3e93eb58-18e4-4960-a483-d51daf6cd6fd",
  • "season_number": 1,
  • "episode_number": 0,
  • "title": "string",
  • "synopsis": "string",
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "images": {},
  • "status": "draft",
  • "air_date": "2019-08-24",
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Episode (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
episode_number
required
integer >= 0
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
season_number
required
integer >= 1
episode_number
required
integer >= 0

0 indicates a special/bonus episode.

title
required
string <= 255 characters
synopsis
string <= 2000 characters
runtime_minutes
integer >= 1

Runtime in minutes. Required before publishing.

content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"

Inherits from show if not set; must be set before publishing.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "draft" "published" "scheduled" "unpublished"
air_date
string <date>

Original broadcast air date.

available_from
string <date-time>
available_until
string <date-time>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "show_id": "503c9125-a11a-4f69-b904-e679735399e2",
  • "season_id": "3e93eb58-18e4-4960-a483-d51daf6cd6fd",
  • "season_number": 1,
  • "episode_number": 0,
  • "title": "string",
  • "synopsis": "string",
  • "runtime_minutes": 1,
  • "content_rating": "G",
  • "images": {},
  • "status": "draft",
  • "air_date": "2019-08-24",
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Episode (Admin)

Authorizations:
OAuth2PKCE
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
episode_number
required
integer >= 0

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Channels (Admin)

Live TV channel management and publishing

List Channels (Admin)

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

q
string <= 200 characters

Full-text search query (max 200 characters).

status
string
Enum: "live" "offline" "scheduled_maintenance"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Channel (Admin)

Authorizations:
OAuth2PKCE
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended — time-ordered, collision-resistant) that makes a write request safely retryable. Replaying the same key within 24h returns the original result instead of performing the action twice. Strongly recommended on all payment and subscription mutations.

Request Body schema: application/json
required
name
required
string <= 100 characters
number
integer >= 1

Logical Channel Number (LCN) for display in the EPG grid.

description
string <= 1000 characters
category
string <= 100 characters

Channel genre category (e.g. News, Sports, Entertainment).

language
string

Primary broadcast language (BCP-47).

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "live" "offline" "scheduled_maintenance"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean
is_premium
required
boolean

Requires a premium or higher plan tier to access.

is_catchup_enabled
required
boolean

Whether catch-up TV (time-shifted replay) is available for this channel.

catchup_days
integer [ 0 .. 30 ]

Number of past days available for catch-up. Null when is_catchup_enabled is false.

sort_order
integer
Default: 0

Display position in channel lists (lower = higher priority).

website_url
string <uri>

Official broadcaster website URL.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Channel (Admin)

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Channel (Admin)

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
name
required
string <= 100 characters
number
integer >= 1

Logical Channel Number (LCN) for display in the EPG grid.

description
string <= 1000 characters
category
string <= 100 characters

Channel genre category (e.g. News, Sports, Entertainment).

language
string

Primary broadcast language (BCP-47).

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

status
required
string
Enum: "live" "offline" "scheduled_maintenance"
object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

drm_required
required
boolean
is_premium
required
boolean

Requires a premium or higher plan tier to access.

is_catchup_enabled
required
boolean

Whether catch-up TV (time-shifted replay) is available for this channel.

catchup_days
integer [ 0 .. 30 ]

Number of past days available for catch-up. Null when is_catchup_enabled is false.

sort_order
integer
Default: 0

Display position in channel lists (lower = higher priority).

website_url
string <uri>

Official broadcaster website URL.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Channel (Admin)

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Publish Channel

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Unpublish Channel

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "number": 1,
  • "description": "string",
  • "category": "News",
  • "language": "en",
  • "images": {},
  • "status": "live",
  • "geo_restrictions": {
    },
  • "drm_required": true,
  • "is_premium": true,
  • "is_catchup_enabled": true,
  • "catchup_days": 30,
  • "sort_order": 0,
  • "website_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

EPG (Admin)

Programme schedule management and bulk import

Get Channel EPG Schedule (Admin)

Returns the full schedule for a channel (past and future). No time window restriction.

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
query Parameters
start_time
string <date-time>
end_time
string <date-time>
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create EPG Programme (Admin)

Authorizations:
OAuth2PKCE
path Parameters
channel_id
required
string <uuid>
Request Body schema: application/json
required
channel_id
required
string <uuid>
title
required
string <= 255 characters
description
string <= 2000 characters
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"
language
string

Programme broadcast language (BCP-47).

start_time
required
string <date-time>
end_time
required
string <date-time>
is_live
required
boolean

True while the programme is currently airing.

is_catchup_available
required
boolean

True when this past programme is available for catch-up replay via /channels/{id}/catchup.

catchup_expires_at
string <date-time>

When catch-up availability expires. Null if not available.

season_number
integer or null

Season number for episodic content broadcast on live TV.

episode_number
integer or null

Episode number within the season.

categories
Array of strings

Genre/category tags.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

linked_vod_id
string <uuid>

Linked VOD asset ID — allows direct navigation to the VOD version.

Responses

Request samples

Content type
application/json
{
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "title": "string",
  • "description": "string",
  • "content_rating": "G",
  • "language": "en",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "is_live": true,
  • "is_catchup_available": true,
  • "catchup_expires_at": "2019-08-24T14:15:22Z",
  • "season_number": 0,
  • "episode_number": 0,
  • "categories": [
    ],
  • "images": {},
  • "linked_vod_id": "657aaad7-6df0-4878-8900-295f294bc20e"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "title": "string",
  • "description": "string",
  • "content_rating": "G",
  • "language": "en",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "duration_minutes": 0,
  • "is_live": true,
  • "is_catchup_available": true,
  • "catchup_expires_at": "2019-08-24T14:15:22Z",
  • "season_number": 0,
  • "episode_number": 0,
  • "categories": [
    ],
  • "images": {},
  • "linked_vod_id": "657aaad7-6df0-4878-8900-295f294bc20e"
}

Update EPG Programme (Admin)

Authorizations:
OAuth2PKCE
path Parameters
program_id
required
string <uuid>
Request Body schema: application/json
required
channel_id
required
string <uuid>
title
required
string <= 255 characters
description
string <= 2000 characters
content_rating
string (ContentRating)
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA" "UNRATED"
language
string

Programme broadcast language (BCP-47).

start_time
required
string <date-time>
end_time
required
string <date-time>
is_live
required
boolean

True while the programme is currently airing.

is_catchup_available
required
boolean

True when this past programme is available for catch-up replay via /channels/{id}/catchup.

catchup_expires_at
string <date-time>

When catch-up availability expires. Null if not available.

season_number
integer or null

Season number for episodic content broadcast on live TV.

episode_number
integer or null

Episode number within the season.

categories
Array of strings

Genre/category tags.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

linked_vod_id
string <uuid>

Linked VOD asset ID — allows direct navigation to the VOD version.

Responses

Request samples

Content type
application/json
{
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "title": "string",
  • "description": "string",
  • "content_rating": "G",
  • "language": "en",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "is_live": true,
  • "is_catchup_available": true,
  • "catchup_expires_at": "2019-08-24T14:15:22Z",
  • "season_number": 0,
  • "episode_number": 0,
  • "categories": [
    ],
  • "images": {},
  • "linked_vod_id": "657aaad7-6df0-4878-8900-295f294bc20e"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "title": "string",
  • "description": "string",
  • "content_rating": "G",
  • "language": "en",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "duration_minutes": 0,
  • "is_live": true,
  • "is_catchup_available": true,
  • "catchup_expires_at": "2019-08-24T14:15:22Z",
  • "season_number": 0,
  • "episode_number": 0,
  • "categories": [
    ],
  • "images": {},
  • "linked_vod_id": "657aaad7-6df0-4878-8900-295f294bc20e"
}

Delete EPG Programme (Admin)

Authorizations:
OAuth2PKCE
path Parameters
program_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Bulk Import EPG Schedule (Admin)

Submits an XMLTV or JSON programme schedule for one or more channels. Returns a job ID for status polling. Large feeds should use source_url.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
format
required
string
Enum: "xmltv" "json"

Encoding of the submitted schedule feed.

source
required
string

The schedule payload. For json, an array of EpgProgram-shaped objects encoded as a string; for xmltv, the XMLTV document. Large feeds should be submitted via source_url instead.

source_url
string <uri>

Allow-listed URL the platform will fetch the feed from (alternative to inline source).

channel_ids
Array of strings <uuid> [ items <uuid > ]

Channels this import applies to. If omitted, channels are resolved from the feed.

replace_window
boolean
Default: true

When true, existing programmes within the feed's time range are replaced.

Responses

Request samples

Content type
application/json
{
  • "format": "xmltv",
  • "source": "string",
  • "source_url": "http://example.com",
  • "channel_ids": [
    ],
  • "replace_window": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "queued",
  • "programs_imported": 0,
  • "errors": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Collections (Admin)

Collection and rail management

List Collections (Admin)

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "draft" "published" "scheduled" "archived"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Collection (Admin)

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
slug
required
string <= 120 characters ^[a-z0-9-]+$
title
required
string <= 200 characters
subtitle
string or null <= 300 characters
type
required
string
Enum: "manual" "dynamic" "editorial" "franchise"

manual = hand-picked items; dynamic = rule/query-driven.

status
required
string
Enum: "draft" "published" "scheduled" "archived"
query
string or null

For dynamic collections, the catalogue filter expression that populates items.

Array of objects

For manual collections, ordered content references.

sort_order
integer

Display weight for ordering collections relative to one another.

object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

available_from
string <date-time>
available_until
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "item_count": 0,
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Collection (Admin)

Authorizations:
OAuth2PKCE
path Parameters
collection_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "item_count": 0,
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Collection (Admin)

Authorizations:
OAuth2PKCE
path Parameters
collection_id
required
string <uuid>
header Parameters
If-Match
string

ETag of the resource version the client last read. Enables optimistic concurrency on writes: the request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
slug
required
string <= 120 characters ^[a-z0-9-]+$
title
required
string <= 200 characters
subtitle
string or null <= 300 characters
type
required
string
Enum: "manual" "dynamic" "editorial" "franchise"

manual = hand-picked items; dynamic = rule/query-driven.

status
required
string
Enum: "draft" "published" "scheduled" "archived"
query
string or null

For dynamic collections, the catalogue filter expression that populates items.

Array of objects

For manual collections, ordered content references.

sort_order
integer

Display weight for ordering collections relative to one another.

object (GeoRestrictionRef)

Inline geo-restriction summary embedded in content responses.

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe.

available_from
string <date-time>
available_until
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "subtitle": "string",
  • "type": "manual",
  • "status": "draft",
  • "query": "string",
  • "item_refs": [
    ],
  • "item_count": 0,
  • "sort_order": 0,
  • "geo_restrictions": {
    },
  • "images": {},
  • "available_from": "2019-08-24T14:15:22Z",
  • "available_until": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Collection (Admin)

Authorizations:
OAuth2PKCE
path Parameters
collection_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Genres (Admin)

Genre taxonomy management

List Genres (Admin)

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create Genre (Admin)

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
name
required
string <= 100 characters
slug
required
string <= 100 characters ^[a-z0-9-]+$
content_types
required
Array of strings
Items Enum: "movie" "show"

Which content types use this genre.

parent_id
string <uuid>

Parent genre UUID for hierarchical taxonomy (e.g. Action → Superhero).

image_url
string <uri>

CDN URL for genre artwork.

Responses

Request samples

Content type
application/json
{
  • "name": "Science Fiction",
  • "slug": "science-fiction",
  • "content_types": [
    ],
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  • "image_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Science Fiction",
  • "slug": "science-fiction",
  • "content_types": [
    ],
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  • "content_count": 0,
  • "image_url": "http://example.com"
}

Update Genre (Admin)

Authorizations:
OAuth2PKCE
path Parameters
genre_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string <= 100 characters
slug
required
string <= 100 characters ^[a-z0-9-]+$
content_types
required
Array of strings
Items Enum: "movie" "show"

Which content types use this genre.

parent_id
string <uuid>

Parent genre UUID for hierarchical taxonomy (e.g. Action → Superhero).

image_url
string <uri>

CDN URL for genre artwork.

Responses

Request samples

Content type
application/json
{
  • "name": "Science Fiction",
  • "slug": "science-fiction",
  • "content_types": [
    ],
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  • "image_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Science Fiction",
  • "slug": "science-fiction",
  • "content_types": [
    ],
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  • "content_count": 0,
  • "image_url": "http://example.com"
}

Delete Genre (Admin)

Fails if any published content references this genre.

Authorizations:
OAuth2PKCE
path Parameters
genre_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

MediaIngest

Resumable media upload and transcoding lifecycle

Initiate Resumable Media Upload

Creates a media upload session and returns a signed upload URL. Upload the source file directly to the URL using a resumable PUT. After upload, call /complete to trigger transcoding.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
asset_type
required
string
Enum: "video_master" "trailer" "image" "subtitle" "audio_track"
filename
required
string <= 255 characters
content_type
required
string

MIME type (e.g. video/mp4, image/jpeg).

size_bytes
required
integer <int64> >= 1
object or null

Content entity to attach the asset to after processing.

Responses

Request samples

Content type
application/json
{
  • "asset_type": "video_master",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 1,
  • "target": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "asset_type": "video_master",
  • "filename": "string",
  • "content_type": "video/mp4",
  • "size_bytes": 1,
  • "upload_url": "http://example.com",
  • "upload_url_expires_at": "2019-08-24T14:15:22Z",
  • "status": "awaiting_upload",
  • "transcode_status": "pending",
  • "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
  • "target": {
    },
  • "error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Upload / Transcode Status

Authorizations:
OAuth2PKCE
path Parameters
upload_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "asset_type": "video_master",
  • "filename": "string",
  • "content_type": "video/mp4",
  • "size_bytes": 1,
  • "upload_url": "http://example.com",
  • "upload_url_expires_at": "2019-08-24T14:15:22Z",
  • "status": "awaiting_upload",
  • "transcode_status": "pending",
  • "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
  • "target": {
    },
  • "error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Upload

Cancels a pending or in-progress upload. Cannot cancel a completed transcode.

Authorizations:
OAuth2PKCE
path Parameters
upload_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Complete Upload and Trigger Transcode

Signals that the source file upload is finished and triggers the transcoding pipeline.

Authorizations:
OAuth2PKCE
path Parameters
upload_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "asset_type": "video_master",
  • "filename": "string",
  • "content_type": "video/mp4",
  • "size_bytes": 1,
  • "upload_url": "http://example.com",
  • "upload_url_expires_at": "2019-08-24T14:15:22Z",
  • "status": "awaiting_upload",
  • "transcode_status": "pending",
  • "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
  • "target": {
    },
  • "error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

GeoRestrictions

Geo-restriction rule management and access checks

List Geo-Restriction Rules (Admin)

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Geo-Restriction Rule (Admin)

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
name
required
string <= 100 characters

Human-readable rule name for admin display.

description
string <= 500 characters
policy
required
string
Enum: "allow_list" "block_list"
territories
required
Array of strings non-empty [ items = 2 characters ]

ISO 3166-1 alpha-2 country codes.

applies_to
Array of strings <uuid> [ items <uuid > ]

Content asset UUIDs this rule is applied to. Empty = rule is unattached.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "policy": "allow_list",
  • "territories": [
    ],
  • "applies_to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "policy": "allow_list",
  • "territories": [
    ],
  • "applies_to": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Geo-Restriction Rule (Admin)

Authorizations:
OAuth2PKCE
path Parameters
rule_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "policy": "allow_list",
  • "territories": [
    ],
  • "applies_to": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Geo-Restriction Rule (Admin)

Authorizations:
OAuth2PKCE
path Parameters
rule_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string <= 100 characters

Human-readable rule name for admin display.

description
string <= 500 characters
policy
required
string
Enum: "allow_list" "block_list"
territories
required
Array of strings non-empty [ items = 2 characters ]

ISO 3166-1 alpha-2 country codes.

applies_to
Array of strings <uuid> [ items <uuid > ]

Content asset UUIDs this rule is applied to. Empty = rule is unattached.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "policy": "allow_list",
  • "territories": [
    ],
  • "applies_to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "policy": "allow_list",
  • "territories": [
    ],
  • "applies_to": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Geo-Restriction Rule (Admin)

Authorizations:
OAuth2PKCE
path Parameters
rule_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Check Geo Access for Content (Admin)

Test whether a given country code can access a specific content asset.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
content_id
required
string <uuid>
content_type
required
string
Enum: "movie" "show" "episode" "channel"
country_code
required
string = 2 characters

Responses

Request samples

Content type
application/json
{
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "content_type": "movie",
  • "country_code": "st"
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "rule_id": "728c1541-d6d1-4290-9a53-cdf01dd32d60"
}

Webhooks

Webhook endpoint management and delivery logs

List Webhook Endpoints

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Webhook Endpoint

Registers a new webhook URL. The system generates an HMAC-SHA256 signing secret; only its last 4 characters are returned in subsequent GET responses. Store the full secret securely on first creation — it cannot be recovered. All deliveries include X-Encora-Signature-256: sha256=<HMAC> header.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
url
required
string <uri>

HTTPS endpoint. HTTP is rejected.

description
string <= 255 characters
events
required
Array of strings (WebhookEventType) non-empty
Items Enum: "subscription.created" "subscription.updated" "subscription.canceled" "subscription.payment_failed" "subscription.trial_ending" "user.created" "user.deleted" "user.suspended" "user.email_verified" "device.registered" "device.removed" "content.published" "content.unpublished" "profile.created" "profile.deleted" "stream.started" "stream.ended" "stream.concurrency_exceeded"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "description": "string",
  • "events": [
    ],
  • "status": "active",
  • "signing_secret_hint": "stri",
  • "failure_count": 0,
  • "last_delivery_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "signing_secret": "string"
}

Get Webhook Endpoint

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "description": "string",
  • "events": [
    ],
  • "status": "active",
  • "signing_secret_hint": "stri",
  • "failure_count": 0,
  • "last_delivery_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Webhook Endpoint

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>
Request Body schema: application/json
required
url
string <uri>
description
string <= 255 characters
events
Array of strings (WebhookEventType)
Items Enum: "subscription.created" "subscription.updated" "subscription.canceled" "subscription.payment_failed" "subscription.trial_ending" "user.created" "user.deleted" "user.suspended" "user.email_verified" "device.registered" "device.removed" "content.published" "content.unpublished" "profile.created" "profile.deleted" "stream.started" "stream.ended" "stream.concurrency_exceeded"
status
string
Enum: "active" "disabled"

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "description": "string",
  • "events": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "description": "string",
  • "events": [
    ],
  • "status": "active",
  • "signing_secret_hint": "stri",
  • "failure_count": 0,
  • "last_delivery_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Webhook Endpoint

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Send Test Webhook Delivery

Sends a synthetic ping event to the endpoint and returns the delivery result.

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "event_type": "subscription.created",
  • "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  • "status": "pending",
  • "http_status": 0,
  • "response_snippet": "string",
  • "attempt_count": 1,
  • "next_retry_at": "2019-08-24T14:15:22Z",
  • "delivered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

List Webhook Delivery Logs

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "pending" "delivered" "failed" "retrying"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Redeliver Failed Webhook

Manually triggers re-delivery of a failed event. Subject to retry rate limits.

Authorizations:
OAuth2PKCE
path Parameters
webhook_id
required
string <uuid>
delivery_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Analytics (Admin)

Platform analytics overview, content, and subscription metrics

Platform Analytics Overview

Returns high-level KPIs — active subscribers, MRR, ARPU, churn, and stream hours.

Authorizations:
OAuth2PKCE
query Parameters
period
required
string
Enum: "today" "last_7d" "last_30d" "last_90d"
currency
string = 3 characters
Default: "USD"

Responses

Response samples

Content type
application/json
{
  • "period": "today",
  • "currency": "str",
  • "total_active_subscribers": 0,
  • "new_subscribers": 0,
  • "churned_subscribers": 0,
  • "net_subscriber_change": 0,
  • "total_stream_hours": 0.1,
  • "avg_daily_active_users": 0.1,
  • "mrr": 0.1,
  • "arpu": 0.1,
  • "churn_rate": 0.1
}

Content Performance Analytics

Returns play counts, unique viewers, and completion rates. Sortable by total_plays or unique_viewers.

Authorizations:
OAuth2PKCE
query Parameters
period
required
string
Enum: "today" "last_7d" "last_30d" "last_90d"
content_type
string
Enum: "movie" "show" "episode" "channel"
limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

cursor
string

Opaque pagination cursor from meta.next_cursor.

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Subscription Analytics

Returns trial conversion rates and revenue breakdown by plan.

Authorizations:
OAuth2PKCE
query Parameters
period
required
string
Enum: "today" "last_7d" "last_30d" "last_90d"

Responses

Response samples

Content type
application/json
{
  • "period": "today",
  • "trial_conversion_rate": 1,
  • "by_plan": [
    ]
}

Audit (Admin)

Immutable audit log access

List Audit Logs

Immutable, append-only audit log. Supports filtering by actor, resource, action, and time range. Results are always sorted newest-first.

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

actor_id
string <uuid>
action
string <= 100 characters

Filter by action prefix (e.g. content. matches all content actions).

resource_type
string <= 100 characters
resource_id
string <uuid>
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get Audit Log Entry

Authorizations:
OAuth2PKCE
path Parameters
log_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "content.published",
  • "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
  • "actor_role": "subscriber",
  • "resource_type": "movie",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "ip_address": "203.0.113.0",
  • "user_agent": "string",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Devices

Device registration and management

List Registered Devices

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 0
}

Register a Device

Registers a new device. Returns 409 if device limit is reached for the plan. The fingerprint field must be a hashed, non-reversible value — never send raw hardware IDs.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
name
required
string <= 100 characters
device_type
required
string
Enum: "smart_tv" "mobile" "tablet" "desktop" "console" "stb" "other"
platform
string <= 100 characters

OS name and version (e.g. "Android 14").

os_version
string <= 50 characters

OS version string.

app_version
string <= 50 characters

App version initiating registration.

fingerprint
required
string <= 512 characters

Opaque hardware/software fingerprint (hashed client-side using SHA-256). Never send raw device identifiers such as IMEI, MAC address, or serial numbers.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "device_type": "smart_tv",
  • "platform": "string",
  • "os_version": "string",
  • "app_version": "string",
  • "fingerprint": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "device_type": "smart_tv",
  • "platform": "Android 14",
  • "os_version": "14.0.1",
  • "app_version": "3.5.2",
  • "is_trusted": true,
  • "last_active_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Device

Authorizations:
OAuth2PKCE
path Parameters
device_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "device_type": "smart_tv",
  • "platform": "Android 14",
  • "os_version": "14.0.1",
  • "app_version": "3.5.2",
  • "is_trusted": true,
  • "last_active_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Rename Device

Authorizations:
OAuth2PKCE
path Parameters
device_id
required
string <uuid>
Request Body schema: application/json
required
name
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "device_type": "smart_tv",
  • "platform": "Android 14",
  • "os_version": "14.0.1",
  • "app_version": "3.5.2",
  • "is_trusted": true,
  • "last_active_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove Device

Removes the device and terminates any active streams on it.

Authorizations:
OAuth2PKCE
path Parameters
device_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

DRM

DRM licence acquisition

Acquire DRM Licence

Accepts a CDM licence challenge and returns a signed DRM licence.

Security Notes

  • Decryption keys are embedded in the licence blob and are never returned in plaintext.
  • The licence is tied to the requesting device ID; playback is restricted to that device.
  • Licences are short-lived (duration set by content rights holder).
  • Audit-logged: content ID, user, device, timestamp, and DRM system are recorded.
Authorizations:
OAuth2PKCE
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

Request Body schema: application/json
required
content_id
required
string <uuid>
content_type
required
string
Enum: "movie" "episode" "channel"
drm_system
required
string
Enum: "widevine" "fairplay" "playready"
license_request_bytes
required
string <byte>

Base64-encoded DRM licence challenge from the CDM.

Responses

Request samples

Content type
application/json
{
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "content_type": "movie",
  • "drm_system": "widevine",
  • "license_request_bytes": "string"
}

Response samples

Content type
application/json
{
  • "license_bytes": "string",
  • "drm_system": "widevine",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "offline_enabled": true,
  • "renewal_before": "2019-08-24T14:15:22Z"
}

Playback

Stream URLs, heartbeat, session management

Stream Heartbeat

Must be called every 30 seconds to maintain an active stream session. Reports current playback position, updates concurrency slot keepalive, and renews the manifest URLs when they approach expiry.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
session_id
required
string <uuid>

Stream session UUID from the stream response.

position_seconds
required
integer >= 0

Current playback position in seconds.

is_paused
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "position_seconds": 0,
  • "is_paused": false
}

Response samples

Content type
application/json
{
  • "refreshed_urls": {
    },
  • "session_expires_at": "2019-08-24T14:15:22Z"
}

End Stream Session

Gracefully terminates a stream session and releases the concurrency slot.

Authorizations:
OAuth2PKCE
path Parameters
session_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

List Active Stream Sessions

Returns all currently active stream sessions for the account.

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Watchlist

Watchlist and watch progress

Get Watchlist

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-release_date

content_type
string
Enum: "movie" "show" "episode"
completed
boolean

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add Item to Watchlist

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
content_type
required
string
Enum: "movie" "show" "episode"
content_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "watch_progress_seconds": 0,
  • "watch_progress_percent": 100,
  • "completed": false,
  • "added_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Watch Progress

Updates the playback position for resume functionality.

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
item_id
required
string <uuid>
Request Body schema: application/json
required
watch_progress_seconds
integer >= 0
completed
boolean

Responses

Request samples

Content type
application/json
{
  • "watch_progress_seconds": 0,
  • "completed": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "watch_progress_seconds": 0,
  • "watch_progress_percent": 100,
  • "completed": false,
  • "added_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove Item from Watchlist

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
item_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Get Watch History

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

content_type
string
Enum: "movie" "episode" "channel"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Clear Entire Watch History

Irreversibly deletes all watch history entries for the profile. Supports GDPR right-to-erasure. Requires confirmation field to prevent accidental deletion. Audit-logged.

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
confirmation
required
string
Value: "CLEAR_HISTORY"

Must send this exact string to confirm the destructive operation.

Responses

Request samples

Content type
application/json
{
  • "confirmation": "CLEAR_HISTORY"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request body is malformed JSON.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Delete Watch History Item

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
item_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Recommendations

Personalized content recommendations

Get Personalized Recommendations

Returns ML-driven content recommendations for the profile. Results are geo-filtered and subscription-aware.

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

content_type
string
Default: "mixed"
Enum: "movie" "show" "mixed"
context
string
Enum: "home" "continue_watching" "because_you_watched" "trending" "new_releases"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Trending Content

Platform-wide trending titles. Geo-filtered by caller's region.

Authorizations:
OAuth2PKCE
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

content_type
string
Default: "mixed"
Enum: "movie" "show" "mixed"
window
string
Default: "this_week"
Enum: "today" "this_week" "this_month"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Recordings

Cloud DVR (nDVR) recordings

List Cloud DVR Recordings

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "scheduled" "recording" "recorded" "failed" "expired"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Schedule a Cloud DVR Recording

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
channel_id
required
string <uuid>
program_id
string <uuid>

EPG programme ID. If provided, start/end times are derived from it.

start_time
required
string <date-time>
end_time
required
string <date-time>
quality
string
Default: "hd"
Enum: "sd" "hd" "fhd" "uhd"

Responses

Request samples

Content type
application/json
{
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "program_id": "70c1146b-e933-4cb2-a789-bbca5312b517",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "quality": "sd"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "program_id": "70c1146b-e933-4cb2-a789-bbca5312b517",
  • "profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
  • "title": "string",
  • "status": "scheduled",
  • "quality": "sd",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "duration_seconds": 0,
  • "size_bytes": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Recording

Authorizations:
OAuth2PKCE
path Parameters
recording_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  • "program_id": "70c1146b-e933-4cb2-a789-bbca5312b517",
  • "profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
  • "title": "string",
  • "status": "scheduled",
  • "quality": "sd",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "duration_seconds": 0,
  • "size_bytes": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete / Cancel Recording

Authorizations:
OAuth2PKCE
path Parameters
recording_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Reminders

EPG programme reminders

List EPG Reminders

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Reminder

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
target_type
required
string
Enum: "epg_program" "live_channel" "upcoming_release"
target_id
required
string <uuid>
notify_before_minutes
integer >= 0
Default: 10
remind_at
required
string <date-time>
channels
Array of strings
Items Enum: "push" "email"

Responses

Request samples

Content type
application/json
{
  • "target_type": "epg_program",
  • "target_id": "d3bcdc92-4191-401b-ad0c-42056c6efab9",
  • "notify_before_minutes": 10,
  • "remind_at": "2019-08-24T14:15:22Z",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
  • "target_type": "epg_program",
  • "target_id": "d3bcdc92-4191-401b-ad0c-42056c6efab9",
  • "status": "scheduled",
  • "notify_before_minutes": 10,
  • "remind_at": "2019-08-24T14:15:22Z",
  • "channels": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Reminder

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
reminder_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Downloads

Offline download management

List Downloads

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "queued" "downloading" "ready" "expired" "failed"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Download (Queue for Offline)

Queues a movie or episode for offline download on the requesting device. Requires an active subscription with download entitlement and available storage quota.

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
header Parameters
X-Device-Id
required
string <= 128 characters

Registered device identifier.

Request Body schema: application/json
required
content_type
required
string
Enum: "movie" "episode"
content_id
required
string <uuid>
quality
required
string
Enum: "SD" "HD" "FHD"

Responses

Request samples

Content type
application/json
{
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "quality": "SD"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "quality": "SD",
  • "status": "queued",
  • "progress_percent": 100,
  • "error_code": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "file_size_bytes": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Download Status

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
download_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "quality": "SD",
  • "status": "queued",
  • "progress_percent": 100,
  • "error_code": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "file_size_bytes": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete / Cancel Download

Cancels a queued/in-progress download or removes a completed one from the device.

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
download_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Ratings

User content ratings

List My Ratings

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Rate Content

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
content_type
required
string
Enum: "movie" "show" "episode"
content_id
required
string <uuid>
value
required
integer [ 1 .. 5 ]
review
string <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "value": 1,
  • "review": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "value": 1,
  • "review": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Rating

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
rating_id
required
string <uuid>
Request Body schema: application/json
required
value
integer [ 1 .. 5 ]
review
string <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "value": 1,
  • "review": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "movie",
  • "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
  • "value": 1,
  • "review": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Rating

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>
rating_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Subscriptions

List Available Plans

Returns all publicly visible subscription plans.

query Parameters
currency
string = 3 characters
Example: currency=USD
billing_cycle
string
Enum: "monthly" "quarterly" "semi_annual" "annual"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Plan Details

path Parameters
plan_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard HD",
  • "description": "string",
  • "price": 9.99,
  • "currency": "USD",
  • "billing_cycle": "monthly",
  • "max_profiles": 1,
  • "max_concurrent_streams": 1,
  • "max_devices": 1,
  • "max_quality": "SD",
  • "has_downloads": true,
  • "allow_download_count": 0,
  • "has_ads": true,
  • "has_hdr": true,
  • "has_dolby_atmos": true,
  • "trial_days": 0,
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}