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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

List Movie Trailers

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Get Movie Subtitle & Audio Tracks

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
path Parameters
show_id
required
string <uuid>

Responses

Response samples

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

List Seasons for a Show

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{}

Get a Specific Season

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

Responses

Response samples

Content type
application/json
{}

List Show Trailers

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>

Responses

Response samples

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

Get Related Shows

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1
episode_number
required
integer >= 0

Responses

Response samples

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

Get Episode Stream URLs

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

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Get Episode Subtitle & Audio Tracks

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

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

Get Live Channel Stream URLs

Returns short-lived signed DASH/HLS manifest URLs for a live channel.

The CMS selects the active primary stream source configured by an admin (via POST /admin/channels/{channel_id}/stream-sources) and signs its origin_url using the source's signing_key_id and token_ttl_seconds. The signed URL is what this response returns — the raw origin URL is never exposed to subscribers.

Validates subscription, geo, device registration, and concurrency before signing. Returns 503 if no active primary stream source is configured.

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Get Catch-Up Stream for a Past Programme

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

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Start Over Current Programme

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

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
path Parameters
program_id
required
string <uuid>

Responses

Response samples

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

Collections

Curated collections and server-driven home layout

List Collections

Returns published collections. Geo-filtered by caller region.

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

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
{
  • "data": {
    }
}

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

Response samples

Content type
application/json
{
  • "code": "INTERNAL_ERROR",
  • "message": "An unexpected error occurred. Please try again later.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

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:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Get Movie (Admin)

Authorizations:
BearerAuth
path Parameters
movie_id
required
string <uuid>

Responses

Response samples

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

Update Movie (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Delete Movie (Admin)

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

Authorizations:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

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:
BearerAuth
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
{
  • "data": {
    }
}

Shows (Admin)

Show authoring, publishing, and unpublishing

List Shows (Admin)

Authorizations:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Get Show (Admin)

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>

Responses

Response samples

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

Update Show (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Delete Show (Admin)

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

Authorizations:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Unpublish Show

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

List Seasons (Admin)

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{}

Create Season (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer >= 1

Responses

Response samples

Content type
application/json
{}

Update Season (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Get Episode (Admin)

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

Responses

Response samples

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

Update Episode (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Delete Episode (Admin)

Authorizations:
BearerAuth
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:
BearerAuth
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)

Creates a new channel. After creation, add one or more stream sources (origin URLs) via POST /admin/channels/{channel_id}/stream-sources and promote the primary with POST .../activate.

Authorizations:
BearerAuth
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 EPG display.

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

Primary broadcast language (BCP-47).

object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
is_catchup_enabled
required
boolean
catchup_days
integer [ 0 .. 30 ]
sort_order
integer
Default: 0
website_url
string <uri>

Responses

Request samples

Content type
application/json
{}

Response samples

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

Get Channel (Admin)

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

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

Update Channel (Admin)

Partial update — send only the fields that should change. To add, rotate, or remove stream sources use /admin/channels/{channel_id}/stream-sources.

Authorizations:
BearerAuth
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
string <= 100 characters
number
integer >= 1
description
string <= 1000 characters
category
string <= 100 characters
language
string
object (ImageSet)

Content artwork. All URLs are CDN-hosted, immutable, and cache-safe. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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

Inline geo-restriction summary embedded in content responses.

drm_required
boolean
is_premium
boolean
is_catchup_enabled
boolean
catchup_days
integer [ 0 .. 30 ]
sort_order
integer
website_url
string <uri>

Responses

Request samples

Content type
application/json
{}

Response samples

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

Delete Channel (Admin)

Authorizations:
BearerAuth
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:
BearerAuth
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

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

Unpublish Channel

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>

Responses

Response samples

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

List Stream Sources

Returns all stream sources configured for a channel, ordered by failover_priority. The raw origin_url is never included in responses.

Authorizations:
BearerAuth
path Parameters
channel_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": {
    }
}

Add Stream Source

Adds a new stream source to a channel. The origin_url is stored encrypted and never returned after this call. If is_primary: true, any existing primary source is automatically demoted.

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
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
label
required
string <= 100 characters
provider
string <= 100 characters

Name of the 3rd party platform that provided this URL.

external_id
string <= 255 characters

Stream or asset ID in the 3rd party platform.

protocol
required
string
Enum: "hls" "dash" "rtmp" "srt"
origin_url
required
string <uri>

Stream URL from the 3rd party platform.

drm_system
required
string
Enum: "widevine" "fairplay" "playready" "none"
signing_key_id
string

CMS signing key reference. Omit if the 3rd party platform handles its own access control.

token_ttl_seconds
integer [ 30 .. 86400 ]
Default: 300
failover_priority
integer >= 1
Default: 10
is_primary
boolean
Default: false
is_active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "label": "Primary HLS",
  • "provider": "Mux",
  • "external_id": "FNRPaVDy5AMW9iJ4b00YTW1bWkKLfIKmA",
  • "protocol": "hls",
  • "origin_url": "https://stream.mux.com/FNRPaVDy5AMW9iJ4b00YTW1bWkKLfIKmA.m3u8",
  • "drm_system": "widevine",
  • "signing_key_id": "key_prod_live_01",
  • "token_ttl_seconds": 300,
  • "failover_priority": 10,
  • "is_primary": false,
  • "is_active": true
}

Response samples

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

Get Stream Source

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
source_id
required
string <uuid>

Responses

Response samples

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

Update Stream Source

Update labels, DRM config, priority, or active status. To rotate the origin URL, include origin_url in the request body — it will be re-encrypted and stored. is_primary cannot be changed directly; use the activate endpoint instead.

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
source_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
label
string <= 100 characters
provider
string <= 100 characters

Update the 3rd party platform name.

external_id
string <= 255 characters

Update the stream/asset ID in the 3rd party platform.

origin_url
string <uri>

New stream URL from the 3rd party platform (replaces the stored URL).

drm_system
string
Enum: "widevine" "fairplay" "playready" "none"
signing_key_id
string or null

Set to null to disable CMS signing (use 3rd party access control instead).

token_ttl_seconds
integer [ 30 .. 86400 ]
failover_priority
integer >= 1
is_active
boolean

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "provider": "string",
  • "external_id": "string",
  • "origin_url": "http://example.com",
  • "drm_system": "widevine",
  • "signing_key_id": "string",
  • "token_ttl_seconds": 30,
  • "failover_priority": 1,
  • "is_active": true
}

Response samples

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

Delete Stream Source

Permanently removes a stream source. Cannot delete the primary source while other active sources exist — promote another source first.

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
source_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"
}

Set as Primary Stream Source

Promotes this source to primary, atomically demoting the previous primary. The source must be active (is_active: true). Subsequent calls to GET /channels/{channel_id}/stream will sign URLs from this source.

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
source_id
required
string <uuid>

Responses

Response samples

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

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:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Update EPG Programme (Admin)

Authorizations:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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
{
  • "data": {
    }
}

Delete EPG Programme (Admin)

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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:
BearerAuth
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:
BearerAuth
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. Manage individual slots via PUT /admin/{resource}/{id}/images/{slot}.

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:
BearerAuth
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:
BearerAuth

Responses

Response samples

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

Create Genre (Admin)

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Update Genre (Admin)

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Delete Genre (Admin)

Fails if any published content references this genre.

Authorizations:
BearerAuth
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"
}

Images (Admin)

Image upload for content artwork — direct multipart upload per slot, or two-step pre-signed URL for direct-to-CDN delivery

Upload Movie Image

Uploads and replaces the image for the given slot. The file is processed (resized, converted) and served from the CDN. The response contains the updated ImageSet with the new CDN URL. Accepted formats: JPEG, PNG, WebP. Maximum size: 10 MB.

Authorizations:
BearerAuth
path Parameters
movie_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, portrait, backdrop, thumbnail, logo.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Image file (JPEG, PNG, or WebP; max 10 MB).

Responses

Response samples

Content type
application/json
{}

Remove Movie Image

Removes the image from the given slot. Returns the updated ImageSet.

Authorizations:
BearerAuth
path Parameters
movie_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, portrait, backdrop, thumbnail, logo.

Responses

Response samples

Content type
application/json
{}

Upload Show Image

Uploads and replaces the image for the given slot. Accepted formats — JPEG, PNG, WebP; max 10 MB.

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, portrait, backdrop, thumbnail, logo.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Remove Show Image

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, portrait, backdrop, thumbnail, logo.

Responses

Response samples

Content type
application/json
{}

Upload Season Image

Uploads the poster artwork for a season. Accepted formats — JPEG, PNG, WebP; max 10 MB.

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slot: poster.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Remove Season Image

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slot: poster.

Responses

Response samples

Content type
application/json
{}

Upload Episode Image

Uploads artwork for an episode. Accepted formats — JPEG, PNG, WebP; max 10 MB.

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer
episode_number
required
integer
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: thumbnail, backdrop.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Remove Episode Image

Authorizations:
BearerAuth
path Parameters
show_id
required
string <uuid>
season_number
required
integer
episode_number
required
integer
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: thumbnail, backdrop.

Responses

Response samples

Content type
application/json
{}

Upload Channel Image

Uploads artwork for a live channel. Accepted formats — JPEG, PNG, WebP; max 10 MB.

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: banner, logo, thumbnail.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Remove Channel Image

Authorizations:
BearerAuth
path Parameters
channel_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: banner, logo, thumbnail.

Responses

Response samples

Content type
application/json
{}

Request Pre-Signed Image Upload URL

Issues a pre-signed URL so the client can upload an image file directly to CDN/object storage — bypassing the API server for large binary payloads.

Two-step flow:

  1. POST here to get upload_url and upload_id.
  2. Upload the file directly to upload_url using the specified upload_method.
  3. POST to /admin/images/confirm with the upload_id to associate the processed CDN URL with the resource.

Alternatively, use PUT /admin/{resource}/{id}/images/{slot} for a single-step multipart upload through the API server.

Authorizations:
BearerAuth
Request Body schema: application/json
required
resource_type
required
string
Enum: "movie" "show" "season" "episode" "channel" "collection"
resource_id
required
string <uuid>

UUID of the target resource.

slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Named artwork slot within an ImageSet. Valid slots per resource:

  • movie / show: poster, portrait, backdrop, thumbnail, logo
  • season: poster
  • episode: thumbnail, backdrop
  • channel: banner, logo, thumbnail
  • collection: poster, backdrop, thumbnail
content_type
required
string
Enum: "image/jpeg" "image/png" "image/webp"

MIME type of the file you intend to upload.

Responses

Request samples

Content type
application/json
{
  • "resource_type": "movie",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "slot": "poster",
  • "content_type": "image/jpeg"
}

Response samples

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

Confirm Direct Image Upload

Confirms that a direct-to-CDN upload has completed and associates the processed CDN URL with the target resource's ImageSet. Call this after successfully uploading to the upload_url returned by /admin/images/upload-url. Triggers image processing (resizing, format conversion, CDN propagation).

Authorizations:
BearerAuth
Request Body schema: application/json
required
upload_id
required
string <uuid>

The upload_id from the /admin/images/upload-url response.

Responses

Request samples

Content type
application/json
{
  • "upload_id": "f2ef591b-135b-46fa-a604-3d4fda5bfbfb"
}

Response samples

Content type
application/json
{}

Upload Collection Image

Uploads artwork for a collection or rail. Accepted formats — JPEG, PNG, WebP; max 10 MB.

Authorizations:
BearerAuth
path Parameters
collection_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, backdrop, thumbnail.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Remove Collection Image

Authorizations:
BearerAuth
path Parameters
collection_id
required
string <uuid>
slot
required
string (ImageSlot)
Enum: "poster" "portrait" "backdrop" "banner" "thumbnail" "logo"

Valid slots: poster, backdrop, thumbnail.

Responses

Response samples

Content type
application/json
{}

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:
BearerAuth
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
{
  • "data": {
    }
}

Get Upload / Transcode Status

Authorizations:
BearerAuth
path Parameters
upload_id
required
string <uuid>

Responses

Response samples

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

Cancel Upload

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

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Get Geo-Restriction Rule (Admin)

Authorizations:
BearerAuth
path Parameters
rule_id
required
string <uuid>

Responses

Response samples

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

Update Geo-Restriction Rule (Admin)

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Delete Geo-Restriction Rule (Admin)

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
path Parameters
webhook_id
required
string <uuid>

Responses

Response samples

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

Update Webhook Endpoint

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Delete Webhook Endpoint

Authorizations:
BearerAuth
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:
BearerAuth
path Parameters
webhook_id
required
string <uuid>

Responses

Response samples

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

List Webhook Delivery Logs

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Content Performance Analytics

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

Authorizations:
BearerAuth
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:
BearerAuth
query Parameters
period
required
string
Enum: "today" "last_7d" "last_30d" "last_90d"

Responses

Response samples

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

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:
BearerAuth
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:
BearerAuth
path Parameters
log_id
required
string <uuid>

Responses

Response samples

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

Devices

Device registration and management

List Registered Devices

Authorizations:
BearerAuth

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:
BearerAuth
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
{
  • "data": {
    }
}

Get Device

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

Responses

Response samples

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

Rename Device

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Remove Device

Removes the device and terminates any active streams on it.

Authorizations:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

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:
BearerAuth
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:
BearerAuth
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:
BearerAuth

Responses

Response samples

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

Watchlist

Watchlist and watch progress

Get Watchlist

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Get Recording

Authorizations:
BearerAuth
path Parameters
recording_id
required
string <uuid>

Responses

Response samples

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

Delete / Cancel Recording

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Cancel Reminder

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Get Download Status

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

Responses

Response samples

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

Delete / Cancel Download

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

Authorizations:
BearerAuth
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:
BearerAuth
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:
BearerAuth
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
{
  • "data": {
    }
}

Update Rating

Authorizations:
BearerAuth
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
{
  • "data": {
    }
}

Delete Rating

Authorizations:
BearerAuth
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"
}

Content Permissions (Admin)

Resource-level access grants for content assets

List Content Grants

Returns all resource-level content grants. Filter by resource type/ID or grantee to audit who can do what to specific assets.

Authorizations:
BearerAuth
query Parameters
resource_type
string
Enum: "movie" "show" "channel" "collection" "epg_channel"

Filter by content resource type.

resource_id
string <uuid>

Filter by content asset ID.

grantee_type
string
Enum: "user" "role"
grantee_id
string <uuid>

Filter by user or role ID.

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 Content Grant

Grants a user or role specific actions on a single content asset. Idempotent on (resource_id, grantee_id, actions) — use PATCH to extend actions on an existing grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
resource_type
required
string
Enum: "movie" "show" "channel" "collection" "epg_channel"
resource_id
required
string <uuid>
grantee_type
required
string
Enum: "user" "role"
grantee_id
required
string <uuid>
actions
required
Array of strings (ContentGrantAction) non-empty
Items Enum: "read" "update" "delete" "publish" "unpublish" "manage_epg" "manage_media"
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "resource_type": "movie",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "grantee_type": "user",
  • "grantee_id": "97e4ba58-efa7-4ea9-9f1b-7100b3a3aa86",
  • "actions": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

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

Get Content Grant

Authorizations:
BearerAuth
path Parameters
grant_id
required
string <uuid>

Responses

Response samples

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

Update Content Grant

Replaces the action list or adjusts expiry on an existing grant.

Authorizations:
BearerAuth
path Parameters
grant_id
required
string <uuid>
Request Body schema: application/json
required
non-empty
actions
Array of strings (ContentGrantAction) non-empty
Items Enum: "read" "update" "delete" "publish" "unpublish" "manage_epg" "manage_media"
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

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

Revoke Content Grant

Permanently removes the grant. The grantee immediately loses the associated actions on that asset.

Authorizations:
BearerAuth
path Parameters
grant_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"
}

Roles (Admin)

Role management — create, update, and delete custom roles; manage user assignments

List CMS Roles

Returns all CMS roles (system and custom), optionally filtered by type or active status.

Authorizations:
BearerAuth
query Parameters
type
string
Enum: "system" "custom"
is_active
boolean
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 CMS Role

Creates a new custom CMS role. name must be unique across all CMS roles. All permission keys must exist in the CMS catalogue. Requires superadmin scope.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string^[a-z][a-z0-9_]{1,63}$
display_name
string
description
string
parent_role_id
string or null <uuid>

Optional parent role for permission inheritance. Max depth 3.

permissions
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "epg_editor",
  • "display_name": "string",
  • "description": "string",
  • "parent_role_id": "7ea77ce3-4218-4d39-ad84-02444a2f4ee7",
  • "permissions": [
    ]
}

Response samples

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

Get CMS Role

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>

Responses

Response samples

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

Update CMS Role

Updates a custom CMS role. System roles are immutable — returns 403. Changing permissions replaces the full set; use GET /admin/roles/{role_id} to read the current set first. Requires superadmin scope.

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>
Request Body schema: application/json
required
non-empty
display_name
string
description
string
parent_role_id
string or null <uuid>
permissions
Array of strings non-empty
is_active
boolean

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "description": "string",
  • "parent_role_id": "7ea77ce3-4218-4d39-ad84-02444a2f4ee7",
  • "permissions": [
    ],
  • "is_active": true
}

Response samples

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

Delete CMS Role

Permanently deletes a custom CMS role and revokes all existing assignments. System roles cannot be deleted. Requires superadmin scope. All deletions are audit-logged.

Authorizations:
BearerAuth
path Parameters
role_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 Role Members

Returns the paginated list of users who currently hold this role.

Authorizations:
BearerAuth
path Parameters
role_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": {
    }
}

List User CMS Role Assignments

Returns all CMS roles currently assigned to the specified user.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

Responses

Response samples

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

Assign CMS Role to User

Grants the specified CMS role to a user. Assigning superadmin requires superadmin scope. All assignments are audit-logged.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Request Body schema: application/json
required
role_id
required
string <uuid>
expires_at
string or null <date-time>

Optional expiry. Omit for a permanent assignment.

Responses

Request samples

Content type
application/json
{
  • "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

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

Revoke CMS Role from User

Removes the CMS role assignment immediately. The user loses all CMS permissions granted exclusively by that role. All revocations are audit-logged.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
role_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"
}

Permissions (Admin)

Permission catalogue, grouping, synchronous permission checks, and per-user effective permission resolution

List CMS Permissions

Returns the full CMS permission catalogue. Filterable by resource.

Authorizations:
BearerAuth
query Parameters
resource
string
Enum: "content" "channels" "epg" "media" "collections" "genres" "analytics" "webhooks" "geo_restrictions" "grants" "roles"

Filter by resource, e.g. content, channels, analytics.

Responses

Response samples

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

List CMS Permission Groups

Returns the full CMS permission catalogue organised into groups. Use this to build a role-editor UI.

Authorizations:
BearerAuth

Responses

Response samples

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

Check Permission

Synchronously evaluates whether a user holds a given permission, optionally scoped to a specific resource.

Intended for internal service-to-service authorisation checks. Responses include evaluated_at to support short-lived client-side caching. Always returns 200; use the allowed field to branch logic.

Rate limit: 600 req / min per calling service.

Authorizations:
BearerAuth
Request Body schema: application/json
required
subject_id
required
string <uuid>

ID of the user whose access is being checked.

permission
required
string

The permission key to evaluate, e.g. users.suspend or content.publish.

resource_type
string

Optional resource type for resource-scoped checks.

resource_id
string <uuid>

Optional ID of the specific resource for resource-scoped checks.

Responses

Request samples

Content type
application/json
{
  • "subject_id": "80e197be-61ad-4068-b4ff-a483fb5c18f9",
  • "permission": "users.suspend",
  • "resource_type": "movie",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f"
}

Response samples

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

Get User Effective CMS Permissions

Returns the complete, deduplicated set of CMS permissions a user holds, resolved across all assigned roles and their inheritance chains. Useful for access-control debugging and UI personalisation.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

Responses

Response samples

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

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
{
  • "data": {
    }
}