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

Users

Subscriber account management

Get My Account

Returns the authenticated user's full profile.

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update My Account

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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

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:
OAuth2PKCE
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
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Update Account Avatar

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

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Profiles

Sub-profile management and PIN

List My Sub-Profiles

Authorizations:
OAuth2PKCE

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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "avatar_url": "http://example.com",
  • "avatar_preset_id": "308d6212-d330-494c-b2e8-dadf2a06a598",
  • "is_primary": true,
  • "pin_protected": false,
  • "content_rating_limit": "G",
  • "language": "en-US",
  • "is_kids": false,
  • "autoplay_next_episode": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Sub-Profile

Authorizations:
OAuth2PKCE
path Parameters
profile_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "avatar_url": "http://example.com",
  • "avatar_preset_id": "308d6212-d330-494c-b2e8-dadf2a06a598",
  • "is_primary": true,
  • "pin_protected": false,
  • "content_rating_limit": "G",
  • "language": "en-US",
  • "is_kids": false,
  • "autoplay_next_episode": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Sub-Profile

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "avatar_url": "http://example.com",
  • "avatar_preset_id": "308d6212-d330-494c-b2e8-dadf2a06a598",
  • "is_primary": true,
  • "pin_protected": false,
  • "content_rating_limit": "G",
  • "language": "en-US",
  • "is_kids": false,
  • "autoplay_next_episode": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Sub-Profile

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

Authorizations:
OAuth2PKCE
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:
OAuth2PKCE
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

Get My Subscription

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "plan": {
    },
  • "status": "trialing",
  • "auto_renew": true,
  • "current_period_start": "2019-08-24T14:15:22Z",
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "next_billing_date": "2019-08-24T14:15:22Z",
  • "cancel_at_period_end": true,
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "payment_method_last4": "stri",
  • "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Create / Start Subscription

Creates a new subscription. Returns 409 if an active subscription already exists.

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

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

Request Body schema: application/json
required
plan_id
required
string <uuid>
payment_method_id
required
string

Payment method token from the payment 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": "string",
  • "coupon_code": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "plan": {
    },
  • "status": "trialing",
  • "auto_renew": true,
  • "current_period_start": "2019-08-24T14:15:22Z",
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "next_billing_date": "2019-08-24T14:15:22Z",
  • "cancel_at_period_end": true,
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "payment_method_last4": "stri",
  • "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Upgrade / Downgrade Plan

Changes the plan. Proration is calculated server-side. Use /subscriptions/preview first to show the cost before committing.

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

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

Request Body schema: application/json
required
plan_id
required
string <uuid>

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "plan": {
    },
  • "status": "trialing",
  • "auto_renew": true,
  • "current_period_start": "2019-08-24T14:15:22Z",
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "next_billing_date": "2019-08-24T14:15:22Z",
  • "cancel_at_period_end": true,
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "payment_method_last4": "stri",
  • "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Subscription

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

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "plan": {
    },
  • "status": "trialing",
  • "auto_renew": true,
  • "current_period_start": "2019-08-24T14:15:22Z",
  • "current_period_end": "2019-08-24T14:15:22Z",
  • "next_billing_date": "2019-08-24T14:15:22Z",
  • "cancel_at_period_end": true,
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "trial_start": "2019-08-24T14:15:22Z",
  • "trial_end": "2019-08-24T14:15:22Z",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "payment_method_last4": "stri",
  • "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Preview Plan Change Cost

Returns proration amounts and next billing date for an upgrade/downgrade without committing.

Authorizations:
OAuth2PKCE
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
{
  • "from_plan_id": "d841a014-75f2-42da-a20a-4836623c2ec7",
  • "to_plan_id": "0910f027-1b25-4687-aad0-d8a5ca6b89a1",
  • "proration_credit": 0.1,
  • "amount_due_now": 0.1,
  • "currency": "string",
  • "next_billing_date": "2019-08-24",
  • "effective": "immediate"
}

List Payment Methods

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

Authorizations:
OAuth2PKCE

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:
OAuth2PKCE
header Parameters
Idempotency-Key
string <= 255 characters

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

Request Body schema: application/json
required
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "card",
  • "brand": "visa",
  • "last4": "stri",
  • "exp_month": 1,
  • "exp_year": 2000,
  • "is_expired": true,
  • "is_default": true,
  • "billing_name": "string",
  • "billing_country": "US",
  • "wallet_email": "user@example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Payment Method

Authorizations:
OAuth2PKCE
path Parameters
pm_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "card",
  • "brand": "visa",
  • "last4": "stri",
  • "exp_month": 1,
  • "exp_year": 2000,
  • "is_expired": true,
  • "is_default": true,
  • "billing_name": "string",
  • "billing_country": "US",
  • "wallet_email": "user@example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove Payment Method

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

Authorizations:
OAuth2PKCE
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:
OAuth2PKCE
path Parameters
pm_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "card",
  • "brand": "visa",
  • "last4": "stri",
  • "exp_month": 1,
  • "exp_year": 2000,
  • "is_expired": true,
  • "is_default": true,
  • "billing_name": "string",
  • "billing_country": "US",
  • "wallet_email": "user@example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Invoices / Billing History

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

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

status
string
Enum: "open" "paid" "uncollectible" "void"

Responses

Response samples

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

Get Invoice

Authorizations:
OAuth2PKCE
path Parameters
invoice_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invoice_number": "INV-2026-00142",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",
  • "status": "draft",
  • "amount": 0.1,
  • "amount_paid": 0.1,
  • "discount_amount": 0,
  • "tax_amount": 0,
  • "amount_due": 0.1,
  • "currency": "str",
  • "description": "string",
  • "period_start": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "due_date": "2019-08-24T14:15:22Z",
  • "paid_at": "2019-08-24T14:15:22Z",
  • "pdf_url": "http://example.com",
  • "line_items": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Validate a Coupon Code

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

Authorizations:
OAuth2PKCE
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:
OAuth2PKCE
path Parameters
code
required
string <= 64 characters

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "initial_value": 0.1,
  • "remaining_value": 0.1,
  • "currency": "string",
  • "status": "active",
  • "redeemed_by": "61b8282b-fd6d-4a53-8c86-650d790b4549",
  • "redeemed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Redeem Gift Card

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

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

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

Request Body schema: application/json
required
code
required
string <= 64 characters

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "initial_value": 0.1,
  • "remaining_value": 0.1,
  • "currency": "string",
  • "status": "active",
  • "redeemed_by": "61b8282b-fd6d-4a53-8c86-650d790b4549",
  • "redeemed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Notifications

In-app notifications

List Notifications

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

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

unread_only
boolean
Default: false

Responses

Response samples

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

Mark All Notifications as Read

Authorizations:
OAuth2PKCE

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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "payment_failed",
  • "priority": "low",
  • "title": "string",
  • "body": "string",
  • "action_url": "http://example.com",
  • "is_read": false,
  • "read_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete Notification

Authorizations:
OAuth2PKCE
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:
OAuth2PKCE

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

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

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:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

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

q
string <= 200 characters

Full-text search query (max 200 characters).

status
string
Enum: "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:
OAuth2PKCE
path Parameters
user_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reinstate Suspended User

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

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "mfa_enabled": false,
  • "terms_accepted_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Plans (Admin)

Subscription plan management

List Plans (Admin)

Returns all plans including inactive ones. Superadmin only.

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

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

Responses

Response samples

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

Create Plan (Admin)

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
name
required
string <= 100 characters
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",
  • "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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard HD",
  • "description": "string",
  • "price": 9.99,
  • "currency": "USD",
  • "billing_cycle": "monthly",
  • "max_profiles": 1,
  • "max_concurrent_streams": 1,
  • "max_devices": 1,
  • "max_quality": "SD",
  • "has_downloads": true,
  • "allow_download_count": 0,
  • "has_ads": true,
  • "has_hdr": true,
  • "has_dolby_atmos": true,
  • "trial_days": 0,
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Plan (Admin)

Authorizations:
OAuth2PKCE
path Parameters
plan_id
required
string <uuid>

Responses

Response samples

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

Update Plan (Admin)

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

Authorizations:
OAuth2PKCE
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
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",
  • "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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard HD",
  • "description": "string",
  • "price": 9.99,
  • "currency": "USD",
  • "billing_cycle": "monthly",
  • "max_profiles": 1,
  • "max_concurrent_streams": 1,
  • "max_devices": 1,
  • "max_quality": "SD",
  • "has_downloads": true,
  • "allow_download_count": 0,
  • "has_ads": true,
  • "has_hdr": true,
  • "has_dolby_atmos": true,
  • "trial_days": 0,
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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:
OAuth2PKCE
path Parameters
plan_id
required
string <uuid>

Responses

Response samples

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

Billing (Admin)

Coupon management, gift cards, and invoice refunds

List Coupons (Admin)

Authorizations:
OAuth2PKCE
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

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

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

Responses

Response samples

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

Create Coupon (Admin)

Authorizations:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "description": "string",
  • "discount_type": "percent",
  • "discount_value": 0.1,
  • "currency": "str",
  • "applicable_plan_ids": [
    ],
  • "max_redemptions": 1,
  • "max_redemptions_per_user": 1,
  • "redemption_count": 0,
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Coupon (Admin)

Authorizations:
OAuth2PKCE
path Parameters
coupon_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "description": "string",
  • "discount_type": "percent",
  • "discount_value": 0.1,
  • "currency": "str",
  • "applicable_plan_ids": [
    ],
  • "max_redemptions": 1,
  • "max_redemptions_per_user": 1,
  • "redemption_count": 0,
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "description": "string",
  • "discount_type": "percent",
  • "discount_value": 0.1,
  • "currency": "str",
  • "applicable_plan_ids": [
    ],
  • "max_redemptions": 1,
  • "max_redemptions_per_user": 1,
  • "redemption_count": 0,
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Coupon (Admin)

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

Authorizations:
OAuth2PKCE
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:
OAuth2PKCE
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:
OAuth2PKCE
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:
OAuth2PKCE
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
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
  • "amount": 0.1,
  • "currency": "string",
  • "reason": "requested_by_customer",
  • "status": "pending",
  • "notes": "string",
  • "provider_refund_id": "string",
  • "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
  • "processed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}