API docs by Redocly

EncoraStream SMS API (2.0.0)

Download OpenAPI specification:

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

Subscriber Management System — billing and subscriber management endpoints for the EncoraStream OTT Platform.

Covers:

  • Subscriber account and profile management
  • Subscription lifecycle (create, upgrade, downgrade, cancel)
  • Payment methods and billing history
  • Coupons and gift cards
  • In-app notifications
  • Privacy: data export and account deletion
  • Admin: user management (list, suspend, reinstate)
  • Admin: subscription plan management
  • Admin: coupon, gift card, and invoice refund management
  • RBAC: roles, permissions, and fine-grained role-permission assignments

Authorization Model

Permissions → Roles → Users

Permissions are assigned to roles via role_permissions (never directly to users). Roles are assigned to users via user_role_assignments with optional expiry. A user may hold multiple roles simultaneously.

JWT contains roles

Every access token payload includes a roles array derived from the user's active role assignments at token-issuance time. Clients may read this for UI decisions (e.g. showing admin menus). Server-side permission evaluation always queries the database.

Fine-grained resource scope

Each role_permission record carries an optional resource_type and resource_id, enabling three tiers of access (first match wins):

Tier Condition Example
1 — Exact permission + resource_type + resource_id User can refund invoice abc-123 only
2 — Type-scoped permission + resource_type User can refund any invoice
3 — Global permission only User can refund anything

Subscriber vs Admin access

Subscriber role permissions are type-scoped (e.g. users.read scoped to resource_type: user). They satisfy API calls that pass a matching resource_type but not no-scope admin list calls. Admin/superadmin permissions are global and satisfy all tiers.

Ownership enforcement

On mutating subscriber endpoints the server additionally verifies the caller owns the target resource. Subscribers cannot modify another user's profiles, payment methods, or notifications. Admins holding a global permission bypass the ownership check.

Users

Subscriber account management

Get My Account

Returns the authenticated user's full profile.

Authorizations:
BearerAuth

Responses

Response samples

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

Update My Account

Authorizations:
BearerAuth
Request Body schema: application/json
required
non-empty
display_name
string <= 100 characters
phone
string <= 20 characters ^\+[1-9]\d{1,14}$
locale
string
timezone
string
country_code
string = 2 characters
preferred_language
string
object

Per-type notification opt-in/opt-out.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "phone": "string",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "st",
  • "preferred_language": "en",
  • "notification_preferences": {
    }
}

Response samples

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

Request Account Deletion

Initiates account deletion. A grace period applies (typically 30 days) during which the user can cancel. At period end, all personal data is permanently erased per GDPR Art. 17. Use /users/me/deletion-request for cancellation.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "scheduled_deletion_at": "2019-08-24T14:15:22Z",
  • "requested_at": "2019-08-24T14:15:22Z"
}

Change Password

Changes the account password. All other sessions are revoked on success.

Authorizations:
BearerAuth
Request Body schema: application/json
required
current_password
required
string <password>
new_password
required
string <password> [ 10 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word",
  • "new_password": "pa$$word_q"
}

Response samples

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

Update Account Avatar

Upload a new avatar image. Maximum 5MB, JPEG or PNG only.

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

Avatar image file (JPEG or PNG, max 5 MB).

Responses

Response samples

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

Profiles

Sub-profile management and PIN

List My Sub-Profiles

Authorizations:
BearerAuth

Responses

Response samples

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

Create Sub-Profile

Creates a new profile. Returns 409 if the plan's profile limit is reached.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string <= 50 characters
avatar_preset_id
string <uuid>

Preset avatar UUID from the platform's avatar library.

pin
string [ 4 .. 6 ] characters ^\d+$

Numeric PIN for profile lock. Required if is_kids is false and PIN protection is desired.

content_rating_limit
string
Default: "TV-MA"
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA"
language
string
is_kids
boolean
Default: false
autoplay_next_episode
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "avatar_preset_id": "308d6212-d330-494c-b2e8-dadf2a06a598",
  • "pin": "string",
  • "content_rating_limit": "G",
  • "language": "string",
  • "is_kids": false,
  • "autoplay_next_episode": true
}

Response samples

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

Get Sub-Profile

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>

Responses

Response samples

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

Update Sub-Profile

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string <= 50 characters
avatar_preset_id
string <uuid>

Preset avatar UUID from the platform's avatar library.

pin
string [ 4 .. 6 ] characters ^\d+$

Numeric PIN for profile lock. Required if is_kids is false and PIN protection is desired.

content_rating_limit
string
Default: "TV-MA"
Enum: "G" "PG" "PG-13" "R" "NC-17" "TV-Y" "TV-G" "TV-PG" "TV-14" "TV-MA"
language
string
is_kids
boolean
Default: false
autoplay_next_episode
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "avatar_preset_id": "308d6212-d330-494c-b2e8-dadf2a06a598",
  • "pin": "string",
  • "content_rating_limit": "G",
  • "language": "string",
  • "is_kids": false,
  • "autoplay_next_episode": true
}

Response samples

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

Delete Sub-Profile

Deletes profile and associated watchlist/progress data. The primary profile cannot be deleted.

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

Verify Profile PIN

Returns a short-lived profile session token. Required before switching to a PIN-protected profile.

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>
Request Body schema: application/json
required
pin
required
string [ 4 .. 6 ] characters ^\d+$

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "profile_token": "string",
  • "expires_in": 3600
}

Subscriptions

Subscription lifecycle and billing

List My Subscriptions

Returns all subscriptions for the authenticated user across all types (svod, live, addon, ppv). Filter by type or status to narrow results.

Authorizations:
BearerAuth
query Parameters
type
string (SubscriptionType)
Enum: "svod" "live" "addon" "ppv"

Filter by subscription type.

status
string
Enum: "trialing" "active" "past_due" "canceled" "paused" "expired"

Responses

Response samples

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

Start Subscription

Creates a new subscription for the authenticated user. The plan's type determines the subscription type. Returns 409 if the user already has an active subscription of that type — cancel or upgrade the existing one first.

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
plan_id
required
string <uuid>
payment_method_id
required
string <uuid>

Payment method UUID from the gateway. Never send raw card data.

coupon_code
string <= 50 characters

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "coupon_code": "string"
}

Response samples

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

Get Subscription

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Responses

Response samples

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

Upgrade / Downgrade Plan

Changes to another plan of the same type. Cross-type plan changes are not permitted — cancel the existing subscription and start a new one instead. Proration is calculated server-side. Use /{subscription_id}/preview first to show the cost to the user before committing.

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

Target plan — must be the same type as the current plan.

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72"
}

Response samples

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

Cancel Subscription

Schedules cancellation at end of the current billing period. Set immediate: true for instant termination (no refund).

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>
Request Body schema: application/json
required
immediate
boolean
Default: false
reason
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "immediate": false,
  • "reason": "string"
}

Response samples

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

Preview Plan Change Cost

Returns proration amounts and next billing date for a plan change without committing.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>
Request Body schema: application/json
required
plan_id
required
string <uuid>
coupon_code
string <= 50 characters

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "coupon_code": "string"
}

Response samples

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

List Payment Methods

Returns saved payment methods. Full card numbers are never returned.

Authorizations:
BearerAuth

Responses

Response samples

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

Add Payment Method

Attaches a tokenised payment method to the account. The payment_method_token must be obtained from the client-side payment SDK (Stripe, Braintree, etc.). Never send raw card data to this API.

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
payment_method_token
required
string

Token from client-side payment SDK. Never send raw card data.

set_as_default
boolean
Default: false
billing_name
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "payment_method_token": "string",
  • "set_as_default": false,
  • "billing_name": "string"
}

Response samples

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

Get Payment Method

Authorizations:
BearerAuth
path Parameters
pm_id
required
string <uuid>

Responses

Response samples

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

Remove Payment Method

Cannot remove the default payment method if an active subscription exists.

Authorizations:
BearerAuth
path Parameters
pm_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 Default Payment Method

Authorizations:
BearerAuth
path Parameters
pm_id
required
string <uuid>

Responses

Response samples

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

List Invoices / Billing History

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: "open" "paid" "uncollectible" "void"

Responses

Response samples

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

Get Invoice

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string <uuid>

Responses

Response samples

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

Validate a Coupon Code

Checks if a coupon code is valid for the current user and plan before applying.

Authorizations:
BearerAuth
Request Body schema: application/json
required
code
required
string <= 50 characters
plan_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "coupon": {
    },
  • "error_code": "not_found"
}

Look Up Gift Card

Returns the current balance and status of a gift card before redemption.

Authorizations:
BearerAuth
path Parameters
code
required
string <= 64 characters

Responses

Response samples

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

Redeem Gift Card

Applies a gift card to the authenticated user's account balance.

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
code
required
string <= 64 characters

Responses

Request samples

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

Response samples

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

Notifications

In-app notifications

List Notifications

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).

unread_only
boolean
Default: false

Responses

Response samples

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

Mark All Notifications as Read

Authorizations:
BearerAuth

Responses

Response samples

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

Mark Notification as Read / Dismissed

Authorizations:
BearerAuth
path Parameters
notif_id
required
string <uuid>
Request Body schema: application/json
required
is_read
boolean

Responses

Request samples

Content type
application/json
{
  • "is_read": true
}

Response samples

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

Delete Notification

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

Privacy

GDPR data export and account deletion

Get Data Export Status (GDPR Art. 20)

Polls the latest export job status. When ready, the response includes a signed, time-limited download URL. The URL expires in 24 hours.

Authorizations:
BearerAuth

Responses

Response samples

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

Request Personal Data Export (GDPR Art. 20)

Queues a data export job. When ready, a download link is emailed to the account address. One pending export per account at a time.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "download_url": "http://example.com",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Request Account Deletion (GDPR Art. 17)

Initiates account deletion with a 30-day grace period. Active subscriptions are canceled immediately (no refund). During grace period the user may log in to cancel the request.

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

Current account password for confirmation.

reason
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "scheduled_deletion_at": "2019-08-24T14:15:22Z",
  • "requested_at": "2019-08-24T14:15:22Z"
}

Cancel Pending Account Deletion

Cancels an active deletion request during the 30-day grace period. Restores full account access. Audit-logged.

Authorizations:
BearerAuth

Responses

Response samples

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

Users (Admin)

User account listing, suspension, and reinstatement

List Users (Admin)

Returns all registered users with filtering support. Results exclude deleted accounts by default.

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: "active" "suspended" "pending_verification" "deleted"
role
string
Enum: "subscriber" "partner" "admin"
country_code
string = 2 characters
created_after
string <date-time>
created_before
string <date-time>

Responses

Response samples

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

Get User (Admin)

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

Responses

Response samples

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

Update User (Admin)

Allows changing a user's status and roles. Requires admin scope. Role escalation to superadmin requires superadmin scope. All changes are audit-logged with actor ID.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Request Body schema: application/json
required
non-empty
status
string
Enum: "active" "suspended"
roles
Array of strings
Items Enum: "subscriber" "partner" "admin"

Responses

Request samples

Content type
application/json
{
  • "status": "active",
  • "roles": [
    ]
}

Response samples

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

Suspend User Account

Immediately suspends the user account. All active sessions and stream concurrency slots are revoked. Suspended users receive 403 on login attempts. Audit-logged with actor ID and reason.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Request Body schema: application/json
required
reason
required
string <= 500 characters

Reason for suspension. Required for audit trail.

notify_user
boolean
Default: true

Whether to send an email notification to the user.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "notify_user": true
}

Response samples

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

Reinstate Suspended User

Restores account access for a suspended user. Audit-logged.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Request Body schema: application/json
optional
note
string <= 500 characters

Optional reinstatement note for the audit record.

Responses

Request samples

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

Response samples

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

Plans (Admin)

Subscription plan management

List Plans (Admin)

Returns all plans including inactive ones. Superadmin only.

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 Plan (Admin)

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string <= 100 characters
type
required
string (SubscriptionType)
Enum: "svod" "live" "addon" "ppv"

Determines what this plan unlocks. A user can hold at most one active subscription per type at a time.

description
string <= 500 characters
price
required
number <double> >= 0
currency
required
string = 3 characters

ISO 4217 currency code.

billing_cycle
required
string
Enum: "monthly" "quarterly" "semi_annual" "annual"
max_profiles
required
integer [ 1 .. 6 ]

Maximum sub-profiles allowed under this plan.

max_concurrent_streams
required
integer [ 1 .. 8 ]

Maximum simultaneous streams across all devices.

max_devices
required
integer [ 1 .. 20 ]

Maximum registered devices allowed.

max_quality
required
string
Enum: "SD" "HD" "FHD" "UHD_4K" "UHD_8K"

Highest supported playback quality.

has_downloads
required
boolean

Whether offline downloads are permitted.

allow_download_count
integer >= 0

Maximum simultaneous downloads per profile. Null = unlimited (if has_downloads is true).

has_ads
required
boolean

Whether this plan includes ad breaks.

has_hdr
boolean

Whether HDR (HDR10 / Dolby Vision) content is accessible on this plan.

has_dolby_atmos
boolean

Whether Dolby Atmos spatial audio is accessible on this plan.

trial_days
integer >= 0
Default: 0

Free trial duration in days. 0 = no trial.

is_active
required
boolean

False means new subscriptions are blocked; existing subscriptions continue.

Responses

Request samples

Content type
application/json
{
  • "name": "Standard HD",
  • "type": "svod",
  • "description": "string",
  • "price": 9.99,
  • "currency": "USD",
  • "billing_cycle": "monthly",
  • "max_profiles": 1,
  • "max_concurrent_streams": 1,
  • "max_devices": 1,
  • "max_quality": "SD",
  • "has_downloads": true,
  • "allow_download_count": 0,
  • "has_ads": true,
  • "has_hdr": true,
  • "has_dolby_atmos": true,
  • "trial_days": 0,
  • "is_active": true
}

Response samples

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

Get Plan (Admin)

Authorizations:
BearerAuth
path Parameters
plan_id
required
string <uuid>

Responses

Response samples

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

Update Plan (Admin)

Changes to price, billing_cycle, or max_* fields only apply to new subscriptions. Existing subscribers are grandfathered until next renewal.

Authorizations:
BearerAuth
path Parameters
plan_id
required
string <uuid>
header Parameters
If-Match
string

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

Request Body schema: application/json
required
name
required
string <= 100 characters
type
required
string (SubscriptionType)
Enum: "svod" "live" "addon" "ppv"

Determines what this plan unlocks. A user can hold at most one active subscription per type at a time.

description
string <= 500 characters
price
required
number <double> >= 0
currency
required
string = 3 characters

ISO 4217 currency code.

billing_cycle
required
string
Enum: "monthly" "quarterly" "semi_annual" "annual"
max_profiles
required
integer [ 1 .. 6 ]

Maximum sub-profiles allowed under this plan.

max_concurrent_streams
required
integer [ 1 .. 8 ]

Maximum simultaneous streams across all devices.

max_devices
required
integer [ 1 .. 20 ]

Maximum registered devices allowed.

max_quality
required
string
Enum: "SD" "HD" "FHD" "UHD_4K" "UHD_8K"

Highest supported playback quality.

has_downloads
required
boolean

Whether offline downloads are permitted.

allow_download_count
integer >= 0

Maximum simultaneous downloads per profile. Null = unlimited (if has_downloads is true).

has_ads
required
boolean

Whether this plan includes ad breaks.

has_hdr
boolean

Whether HDR (HDR10 / Dolby Vision) content is accessible on this plan.

has_dolby_atmos
boolean

Whether Dolby Atmos spatial audio is accessible on this plan.

trial_days
integer >= 0
Default: 0

Free trial duration in days. 0 = no trial.

is_active
required
boolean

False means new subscriptions are blocked; existing subscriptions continue.

Responses

Request samples

Content type
application/json
{
  • "name": "Standard HD",
  • "type": "svod",
  • "description": "string",
  • "price": 9.99,
  • "currency": "USD",
  • "billing_cycle": "monthly",
  • "max_profiles": 1,
  • "max_concurrent_streams": 1,
  • "max_devices": 1,
  • "max_quality": "SD",
  • "has_downloads": true,
  • "allow_download_count": 0,
  • "has_ads": true,
  • "has_hdr": true,
  • "has_dolby_atmos": true,
  • "trial_days": 0,
  • "is_active": true
}

Response samples

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

Deactivate Plan (Admin)

Marks a plan as inactive — new subscriptions to this plan are blocked. Existing subscriptions continue until they are canceled or expire naturally. Plans with active subscribers cannot be hard-deleted. Audit-logged.

Authorizations:
BearerAuth
path Parameters
plan_id
required
string <uuid>

Responses

Response samples

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

Subscriptions (Admin)

Admin subscription management — assign, modify, cancel, pause, resume, extend, and reactivate subscriptions on behalf of any user

List All Subscriptions

Returns subscriptions across all users. Supports filtering by type, status, plan, and date range. Results are ordered by created_at descending.

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).

type
string (SubscriptionType)
Enum: "svod" "live" "addon" "ppv"

Filter by subscription type.

status
string
Enum: "trialing" "active" "past_due" "canceled" "paused" "expired"

Filter by subscription status.

plan_id
string <uuid>

Filter by plan.

created_after
string <date-time>
created_before
string <date-time>

Responses

Response samples

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

List User Subscriptions

Returns all subscriptions for a specific user across all types. A user may hold one active subscription per type simultaneously.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
query Parameters
type
string (SubscriptionType)
Enum: "svod" "live" "addon" "ppv"

Subscription type determines what content or service the plan unlocks:

  • svod — Main on-demand library (movies, shows, episodes).
  • live — Live TV channels package.
  • addon — Bolt-on add-on package (e.g. premium sports, premium channels).
  • ppv — Pay-per-view event access (time-limited). A user may hold at most one active subscription of each type simultaneously.
status
string
Enum: "trialing" "active" "past_due" "canceled" "paused" "expired"
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": {
    }
}

Assign Subscription to User

Assigns a plan to a user on their behalf. The plan's type determines the subscription type. Payment method is optional — admins can grant complimentary or manually-billed subscriptions. Returns 409 if the user already has an active subscription of that type.

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

Plan to assign to the user.

payment_method_id
string or null <uuid>

Payment method to charge. Null for complimentary or manually-billed subscriptions where no automatic charge is needed.

coupon_code
string <= 50 characters

Optional coupon to apply at assignment.

trial_end
string <date-time>

Override trial end date. If omitted and the plan has a trial period, the standard trial applies. Set to a past date to skip the trial.

current_period_end
string <date-time>

Override the first billing period end. Useful for prorating a partial month when migrating a user from another platform.

auto_renew
boolean
Default: true

Whether the subscription renews automatically at period end.

admin_note
string <= 500 characters

Internal note recorded in the audit log. Not visible to the user.

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "coupon_code": "string",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "auto_renew": true,
  • "admin_note": "string"
}

Response samples

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

Get User Subscription

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>

Responses

Response samples

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

Update User Subscription

Partially updates a subscription — change plan (within same type), swap payment method, toggle auto-renew, override period end, or schedule cancellation. All changes are audit-logged with the acting admin's identity.

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

Change the subscribed plan (upgrade or downgrade). Proration applied automatically.

payment_method_id
string or null <uuid>

Swap the payment method. Null removes the payment method (switches to manual billing).

auto_renew
boolean

Enable or disable automatic renewal.

current_period_end
string <date-time>

Override the current period end date directly.

cancel_at_period_end
boolean

Schedule or unschedule cancellation at period end.

admin_note
string <= 500 characters

Internal note recorded in the audit log.

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "auto_renew": true,
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "cancel_at_period_end": true,
  • "admin_note": "string"
}

Response samples

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

Cancel User Subscription

Cancels a specific subscription. Access continues until period end by default. Set immediate: true to terminate instantly. Audit-logged with reason.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>
Request Body schema: application/json
required
immediate
boolean
Default: false
reason
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "immediate": false,
  • "reason": "string"
}

Response samples

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

Pause Subscription

Suspends billing and access. Status changes to paused. Optionally schedule automatic resumption via resume_at.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>
Request Body schema: application/json
optional
resume_at
string <date-time>

Schedule automatic resumption. Null for indefinite pause.

reason
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "resume_at": "2019-08-24T14:15:22Z",
  • "reason": "string"
}

Response samples

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

Resume Subscription

Resumes a paused subscription. Billing restarts from the resume date; the period end is extended by the paused duration.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>

Responses

Response samples

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

Reactivate Subscription

Reactivates a canceled or expired subscription, optionally on a different plan of the same type. A new billing period starts from the reactivation date.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>
Request Body schema: application/json
optional
plan_id
string <uuid>

Plan to reactivate on (must be same type). Defaults to the previous plan.

payment_method_id
string or null <uuid>
admin_note
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "admin_note": "string"
}

Response samples

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

Extend Subscription

Extends the current billing period by a given number of days without charging the user. Used for goodwill extensions, outage compensation, or manual proration adjustments. Audit-logged.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
subscription_id
required
string <uuid>
Request Body schema: application/json
required
days
required
integer [ 1 .. 365 ]

Number of days to add to the current period end.

reason
string <= 500 characters

Reason recorded in the audit log.

Responses

Request samples

Content type
application/json
{
  • "days": 1,
  • "reason": "string"
}

Response samples

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

Billing (Admin)

Coupon management, gift cards, and invoice refunds

List Coupons (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: "active" "expired" "disabled"

Responses

Response samples

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

Create Coupon (Admin)

Authorizations:
BearerAuth
Request Body schema: application/json
required
code
required
string <= 50 characters ^[A-Z0-9_-]+$

Human-readable coupon code. Uppercase alphanumeric, hyphens, underscores.

description
string <= 500 characters
discount_type
required
string
Enum: "percent" "fixed_amount" "free_trial_days"
discount_value
required
number <double>

Interpretation depends on discount_type: percent — percentage off (1–100). fixed_amount — flat discount in currency. free_trial_days — number of free trial days (integer).

currency
string = 3 characters

ISO 4217 currency code. Required and only applicable when discount_type is fixed_amount.

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

Plan UUIDs this coupon applies to. Empty array = applies to all plans.

max_redemptions
integer >= 1

Maximum total redemptions allowed. Null = unlimited.

max_redemptions_per_user
integer >= 1
Default: 1

Maximum redemptions allowed per individual user account.

valid_from
required
string <date-time>

Coupon becomes active at this timestamp (UTC).

valid_until
string <date-time>

Coupon expires at this timestamp. Null = no expiry date.

status
required
string
Enum: "active" "expired" "disabled"

active — usable. expired — past valid_until; system-managed. disabled — manually deactivated by admin.

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "discount_type": "percent",
  • "discount_value": 0.1,
  • "currency": "str",
  • "applicable_plan_ids": [
    ],
  • "max_redemptions": 1,
  • "max_redemptions_per_user": 1,
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "status": "active"
}

Response samples

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

Get Coupon (Admin)

Authorizations:
BearerAuth
path Parameters
coupon_id
required
string <uuid>

Responses

Response samples

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

Update Coupon (Admin)

Allowed updates: status (disable/re-enable), max_redemptions, valid_until, description. code, discount_type, and discount_value are immutable after creation.

Authorizations:
BearerAuth
path Parameters
coupon_id
required
string <uuid>
Request Body schema: application/json
required
status
string
Enum: "active" "disabled"
max_redemptions
integer >= 1
valid_until
string <date-time>
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "status": "active",
  • "max_redemptions": 1,
  • "valid_until": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Response samples

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

Delete Coupon (Admin)

Hard-deletes a coupon. Forbidden if the coupon has been redeemed (disable instead).

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

Create Gift Cards (Admin)

Bulk-generates gift cards with a specified value.

Authorizations:
BearerAuth
Request Body schema: application/json
required
quantity
required
integer [ 1 .. 500 ]
initial_value
required
number <float> >= 0.01
currency
required
string = 3 characters
expires_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "quantity": 1,
  • "initial_value": 0.01,
  • "currency": "str",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

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

List Refunds for Invoice (Admin)

Returns all refunds issued against a specific invoice.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string <uuid>

Responses

Response samples

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

Issue Invoice Refund (Admin)

Initiates a refund against an invoice. Refunds are audit-logged with the actor ID. Partial refunds are supported.

Authorizations:
BearerAuth
path Parameters
invoice_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
amount
required
number <float> >= 0.01

Refund amount (must be ≤ invoice amount_paid).

reason
required
string
Enum: "requested_by_customer" "duplicate" "fraudulent" "service_issue" "goodwill"
notes
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 0.01,
  • "reason": "requested_by_customer",
  • "notes": "string"
}

Response samples

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

Roles (Admin)

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

List Roles

Returns all platform roles (system-built-in and custom).

Authorizations:
BearerAuth
query Parameters
type
string
Enum: "system" "custom"

Filter by role type.

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 Role

Creates a new custom role. name must be unique. 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
permissions
required
Array of strings non-empty
parent_role_id
string or null <uuid>

Optional parent role ID for inheritance. Max depth 3.

Responses

Request samples

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

Response samples

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

Get Role

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>

Responses

Response samples

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

Update Role

Updates a custom role's display name, description, or permission set. System roles are read-only — 403 is returned if attempted. 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
permissions
Array of strings non-empty
parent_role_id
string or null <uuid>
is_active
boolean

Responses

Request samples

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

Response samples

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

Delete Role

Permanently deletes a custom role and revokes all existing assignments. System roles cannot be deleted. Requires superadmin scope.

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 User Role Assignments

Returns all 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 Role to User

Grants the specified 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 Role from User

Removes the role assignment. The user immediately loses all permissions granted exclusively by that role. Revoking superadmin requires superadmin scope. 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"
}

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

Permissions (Admin)

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

List Permissions

Returns all discrete permissions defined in the platform. Use this to build a role editor UI.

Authorizations:
BearerAuth
query Parameters
resource
string

Filter by resource, e.g. users, billing, content.

Responses

Response samples

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

Get User Effective Permissions

Returns the complete, deduplicated set of permissions a user holds, derived from all their assigned roles. Useful for access-control debugging.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

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

List Permission Groups

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

Authorizations:
BearerAuth

Responses

Response samples

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