This page maps client use cases to API endpoints, broken down by microservice and grouped by business service.
If there is an existing use case, a link is included.
It is a work in progress.
Authentication, authorisation, and entitlements
User authorisation
Identity Authentication Service (IAS)
IAS also provides endpoints for content authorisation and a number of other things – see Entitlements and content authorisation.
V3 OAuth
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Retrieve device token using username, password, and device details. |
|
Also mentioned in
|
|
|
Retrieve device token using the device's |
|
|
|
|
Retrieve device token using the device's smartcard identifier. |
|
|
|
|
Retrieve signon token using TVKey activation and optional device information. In order for the API to work, the device must be pre-provisioned. |
|
|
|
|
Refresh signon token |
|
|
|
|
Sign out |
|
|
V3 DAS
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Validates user and password credentials from the request body, get deviceId from DAS-Server, creating a new device and returns an SSP Token with optional device information |
|
|
V3 SSO Signon
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
SignOn to OPF using a SignOnActivation Token created by DSRA |
|
Part of
|
V3 self-service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Self-service token |
|
|
V2 self-service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Self Service Token deprecated due to sensitive information in parameters |
|
Not actually deprecated, but there is a v3 version. |
V2 OAuth Signon [DEPRECATED]
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get device token (four variants) |
|
|
V2 Sign out [DEPRECATED]
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Sign out |
|
|
Authentication Gateway (AGS)
Authentication Service Discovery Service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Discover auth services |
|
|
Session Token Services
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Retrieve SignOn token using provided sessionToken |
|
|
|
|
Obtains a sessionToken for subsequent use in calls to /signOnWithSessionToken. |
|
|
Authentication Services
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Retrieve SignOn token using provided credentials. |
|
|
|
|
Subsequent SignOn to be used when the initial SignOn endpoint returns a 300 to indicate there are multiple accounts associated with the user. |
|
|
|
|
Refreshes a SignOn token |
|
|
|
|
Signs Out from an account |
|
|
Registration Services
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Register using provided credentials. |
|
|
|
|
Subsequent Registration to be used when the initial Register endpoint returns a 300 to indicate there are multiple accounts associated with the user. |
|
|
Device SignOn and Registration Assistant (DSRA)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get a Device Registration Code and DSRA Token. |
||
|
|
Obtain a SignOn Activation Token. |
||
|
|
Approve a Device Registration Code. |
Entitlements and content authorisation
Identity Authentication Service (IAS)
IAS also provides endpoints for user authentication – see User authentication.
UserProfile
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Change (switch) user profile |
|
|
Content Authorization
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get content token with CDN token |
|
|
|
|
Get content token |
|
Also in “Fetching the content token” in
|
|
|
Get content token for PPV event |
|
|
|
|
Get content token for Download2Go |
|
D2Go is documented here:
But this endpoint is not mentioned. |
Token Validation Service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Validate and decode an OPF3 JWT token. |
|
|
Location detection services
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Test for in-house by IP address |
|
|
DAS Service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Validate credentials and get device ID from DAS |
|
|
|
|
Get device ID using devAuthToken and DAS SDK data |
|
|
V1 Locale Information
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Returns the locale information for the clients IP Address |
|
|
Rights Manager (RMG)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get all capability type Entitlements |
|
|
|
|
Get a user Entitlement |
The use cases uses the wrong endpoint ( |
|
|
|
Get a user Entitlements |
|
|
|
|
Get a list of User Entitlements for the requesting device. |
|
|
Guest Entitlement Service (GES)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Create a room. |
||
|
|
Join a room. |
||
|
|
Get the status and membership of a room. |
Purchase Service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Purchase a product |
|
Account details and management
ADM
Accounts Service – User
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get account by ID (that is, |
|
|
|
|
Change password |
|
This is only applicable where OPF is being used for sign-on (that is, not SSO). |
|
|
Get PINs for the account (that is, whether a PIN is set for the account for each PIN type, not the actual values of the PINs) |
|
These are all under the General PIN management section. |
|
|
Validate PIN |
||
|
|
Change PIN |
||
|
|
Create PIN |
||
|
|
Get status of all PINs |
Device Approval Service - User
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Check if device is approved. |
All in Device limits section |
|
|
|
Approve/unapprove a device. |
||
|
|
Get next available approval time. |
Check next available approval time and number of approved devices |
Parental Control Service – User
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get parental rating thresholds for an account. |
All in the Parental controls section |
|
|
|
Update parental rating thresholds for an account. |
||
|
|
Delete parental rating thresholds for an account. |
Activity Gateway
User Activity
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Log a new rating request (This is just a specialization of the raw useractivity api) |
|
|
|
|
Log a new activity |
|
|
Bookmarks
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Creates or updates an existing bookmark for account |
|
|
|
|
Deletes an existing bookmark for a given account |
|
|
|
|
Deletes all existing bookmarks for a given account. Only one query param may be passed. |
|
|
|
|
Deletes an existing bookmark for a given account based on tagId |
|
|
|
|
Creates or updates an existing bookmark for user |
|
|
|
|
Deletes an existing bookmark for a given user |
|
|
|
|
Deletes an existing bookmark for a given user based on tagId |
|
|
Favourites Lists
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Creates a new favouriteslist for account |
|
|
|
|
Updates an existing account's favouriteslist |
|
|
|
|
Deletes an existing account's favouriteslist and all entries |
|
|
|
|
Adds a favourite to an account's favouriteslist |
|
|
|
|
Removes a favourite from an account's favouriteslist |
|
|
|
|
Creates a new favouriteslist for a user |
|
|
|
|
Updates an existing user's favouriteslist |
|
|
|
|
Deletes an existing user's favouriteslist and all entries |
|
|
|
|
Adds a favourite to a favouriteslist |
|
|
|
|
Removes a favourite from a favouriteslist |
|
|
Histories
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Creates History for account |
|
|
|
|
Deletes an existing history entry |
|
|
|
|
Creates history for user |
|
|
|
|
Deletes an existing history entry |
|
|
Playlists
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Adds a playlist entry to an account's playlist |
|
|
|
|
Removes a playlist entry from an account's playlist |
|
|
|
|
Updates an existing account's playlist |
|
|
|
|
Deletes an existing account's playlist and all entries |
|
|
|
|
Creates a new playlists for account |
|
|
|
|
Removes a playlistEntry from a playlist |
|
|
|
|
Updates an existing user's playlist |
|
|
|
|
Deletes an existing user's playlist and all entries |
|
|
|
|
Creates a new playlists for a user |
|
|
Reminders
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Creates a new reminder for an account |
|
|
|
|
Deletes an existing reminder for a given user |
|
|
|
|
Creates a new reminder |
|
|
|
|
Deletes an existing reminder for a given user |
|
|
User Activity Vault (UAV)
Notifications
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get any view counts that have been incremented since the provided startDate |
|
|
|
|
Obtain the notifications for any modifications made to average ratings |
|
|
Ratings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get all ratings logged by the given account results include ratings by all users that belong to that account |
|
|
|
|
Get a specific rating made by a user-account combination |
|
|
|
|
Obtain a list of ratings made by a specific account for the given content returns a number of ratings if there's more than one user per account |
|
|
|
|
Get ratings by all users and accounts made against the specified content |
|
|
|
|
Get all ratings logged by the given user for a specific account |
|
|
|
|
Obtain the average rating for a given piece of content |
Retrieve the average rating for a BTV content
|
|
User Activity
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Log a new rating request (This is just a specialization of the raw useractivity api) |
|
|
|
|
Query for a list of activities logged by a specific account and user |
|
|
|
|
Query for a list of activities logged by a specific account |
|
|
|
|
Log a new activity |
|
|
Bookmarks
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Gets a bookmark for a given account and content |
Get a single bookmark for a content item
|
|
|
|
Creates or updates an existing bookmark for account |
|
|
|
|
Deletes an existing bookmark for a given account |
|
|
|
|
Gets all bookmarks for a given account |
Get all bookmarks for an account
|
|
|
|
Deletes all existing bookmarks for a given account. |
Delete all bookmarks for an account Delete all bookmarks for an account for a series/season Delete all bookmarks created before or after a certain date for an account
|
|
|
|
Deletes an existing bookmark for a given account based on tagId |
|
|
|
|
Gets a bookmark for a given user and content |
|
|
|
|
Creates or updates an existing bookmark for user |
|
|
|
|
Deletes an existing bookmark for a given user |
|
|
|
|
Gets all bookmarks for a given user |
|
|
|
|
Deletes an existing bookmark for a given account based on tagId |
|
|
Favourites Lists
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Gets all favouriteslists for a given account |
Get favourites lists for an account
|
|
|
|
Creates a new favouriteslist for account |
|
|
|
|
Gets all favourites from a list for a given account |
Get all favourites in a favourites list
|
|
|
|
Updates an existing account's favouriteslist |
|
|
|
|
Deletes an existing account's favouriteslist and all entries |
|
|
|
|
Return a group of favourites based on contentId |
|
|
|
|
Adds a favourite to an account's favouriteslist |
Add a favourite to a favourites list
|
|
|
|
Removes a favourite from an account's favouriteslist |
Delete a favourite from a favourites list
|
|
|
|
Gets all favouriteslists for a given user |
|
|
|
|
Creates a new favouriteslist for a user |
|
|
|
|
Gets all favourites from list for a given user |
|
|
|
|
Updates an existing user's favouriteslist |
|
|
|
|
Deletes an existing user's favouriteslist and all entries |
|
|
|
|
Return a group of favourites based on contentId |
|
|
|
|
Adds a favourite to a favouriteslist |
|
|
|
|
Removes a favourite from a favouriteslist |
|
|
Histories
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Gets all Histories for a given account |
|
|
|
|
Creates History for account |
|
|
|
|
Deletes an existing history entry |
|
|
|
|
Gets all Histories for a given account |
|
|
|
|
Creates history for user |
|
|
|
|
Deletes an existing history entry |
|
|
Playlists
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Adds a playlist entry to an account's playlist |
|
|
|
|
Removes a playlist entry from an account's playlist |
|
|
|
|
Gets all playlist from a list for a given account |
|
|
|
|
Updates an existing account's playlist |
|
|
|
|
Deletes an existing account's playlist and all entries |
|
|
|
|
Gets all playlists for a given account |
|
|
|
|
Creates a new playlists for account |
|
|
|
|
Adds a playlist entry to a playlist |
|
|
|
|
Removes a playlistEntry from a playlist |
|
|
|
|
Gets all playlist entry from list for a given user |
|
|
|
|
Updates an existing user's playlist |
|
|
|
|
Deletes an existing user's playlist and all entries |
|
|
|
|
Gets all playlists for a given user |
|
|
|
|
Creates a new playlists for a user |
|
|
Reminders
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Gets reminders for a given user |
|
|
|
|
Creates a new reminder for an account |
|
|
|
|
Deletes an existing reminder for a given user |
|
|
|
|
Gets reminders for a given user |
|
|
|
|
Creates a new reminder |
|
|
|
|
Deletes an existing reminder for a given user |
|
|
URL Builder
contentToken
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Request for CDN token |
|
ppvContentToken
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Request for CDN token for PPV |
|
|
playoutByChannel
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Request for customisation of URL based on channel |
|
|
User Profiles Service
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get all of the User Profiles for an Account |
|
|
|
|
Creates a User Profile for an account |
|
|
|
|
Get User Profile |
|
|
|
|
Update a User Profile on an account |
|
|
|
|
Delete a User Profile from an Account |
|
Business Infrastructure
Open Device Messaging (ODM)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Registers an open device for platform/system notifications. |
|
Content Discovery
Cast, Crew, and Persona Service (CCP)
CastCrewPersonas
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Returns one or more cast/persona entries |
|
|
Users
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Returns the details of the user for the given account and user Id |
|
|
|
|
Updates the details of the user for the given account and user Id |
|
|
|
|
Removes the entry of the user for the given account and user Id |
|
|
|
|
Returns one or more users |
|
|
Content Delivery
Client V1
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get a list of unpopulated templateviews. |
|
|
|
|
Get a list of unpopulated templateviews (no rails), allowing the client to "browse" and choose one. |
|
|
|
|
Get an unpopulated templateview by id (no rails). |
|
|
|
|
Get a tempate skeleton which list rail ids |
|
|
|
|
Get the contents of all the rails within a template |
(25.12_Q1) Retrieve all or part of the rails and related content for a template |
|
|
|
Get the contents of a rail |
|
|
|
|
Get the IDs and properties of all the rails for the requested template, without any related data. |
Missing from latest Content Delivery OAS |
Client V2
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get the contents of all the rails within a template |
This appends |
|
|
|
Get the contents of a rail |
|
|
Content Discovery Facade
EPG
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get programmes for a given time period across all channels, or for a specific channel |
|
|
|
|
Get current programmes available across all channels |
Retrieving previous/now/next programmes – pre-defined queries |
|
Catchup
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get catchup content |
|
|
|
|
Get catchup content for a specific event |
|
|
Media Card
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get mediacard for live programme |
|
|
|
|
Get mediacard for VOD content |
|
|
|
|
Get mediacard for recording |
|
|
|
|
Get mediacard for series |
|
|
Subscribed
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get products to which the account (known from the authentication details) can get their products |
Retrieving products for an authenticated account – predefined query |
|
Content Discovery Gateway (CDG)
Bookmarks
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Add entry to an accounts bookmark list. |
|
|
Contexts
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get contexts. |
Ratings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Rate content |
|
Recommendations
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get recommendations. |
User Activity
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Record user activity |
ImageService
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Retrieve the image that matches the provided imageId |
|
|
|
|
Retrieve an image that best matches the supplied criteria |
|
Image Metadata Service
Get user profile icons
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Returns profile records. |
|
Metadata Server (MDS)
VOD
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Browse Video on Demand (VoD) Catalogues |
|
|
|
|
Browse Video on Demand (VoD) Assets |
|
|
|
|
Browse Video on Demand (VoD) Series |
|
|
|
|
Video On Demand (VoD) Products |
|
BTV
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Browse Broadcast TV (BTV) Channels |
|
|
|
|
Browse Broadcast TV (BTV) Programmes - EPG |
|
|
|
|
List programmes a client is banned from viewing |
|
|
|
|
Browse Broadcast TV (BTV) Series |
|
|
|
|
Browse Broadcast TV (BTV) Products |
|
Changes
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Gets changes to entities since a certain timestamp |
Under Metadata change alerts |
Recommendations Facade
Recommendations
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get recommendations for provided input |
|
User Activity
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Record user activity related to a piece of content |
|
Search Facade
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Make a request for list of search engines |
|
Mentioned in Content Search |
|
|
Make a search request |
|
|
|
|
Get typeahead suggestions based on partial search inputs |
Content Workflow
User Recordings
Aggregated recordings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get aggregated recordings for the current account |
|
|
Quota management
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Return an account's cloud DVR quota usage |
|
|
|
|
Return a user's quotaUsage based on seriesId in seconds |
|
Recordings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get recordings for the given account with various filtering and sorting options |
|
There is a use case that uses |
|
|
Request for a new recording to be scheduled |
|
|
|
|
Cancel / delete a recording |
|
|
|
|
Get recordings of episodes of the given series for the given account with various filtering and sorting options |
|
There is a use case that uses |
Manage recordings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Cancel / delete a recording |
|
|
|
|
Update / patch a recording with isProtected tag. |
|
|
|
|
Cancel / delete a recording |
|
|
Series recordings
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Request for a series recording to be repaired |
|
|
|
|
Get series recordings for the current account |
|
|
|
|
Request for a new series recording to be created |
|
|
|
|
Remove a series recording |
|
|
|
|
Remove a series recording |
|
|
|
|
Update a single Series Recording |
|
|
|
|
Remove a series recording |
|
|
|
|
Get status of series recordings for the current account |
|
|
|
|
Get status of series recordings for the queried account |
|
|
|
|
Update a Single Series Recording, Recording Options |
|
|
Recordings (v2)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get recordings for the given account with various filtering and sorting options |
|
|
|
|
Get recordings of episodes of the given series for the given account with various filtering and sorting options |
|
|
Series recordings (v2)
|
Endpoint |
Description |
Use case(s) |
Comments |
|---|---|---|---|
|
|
Get series recordings for the current account |
|