SKILL LEVEL: Developer
This article is for programmers and developers who wish to build their own custom viewer experience leveraging the BoxCast API.
Common Use Cases
Building a custom channel/broadcast listing into your site or app. For example, see https://github.com/boxcast/example_video_portal_vuejs
Using a non-BoxCast video player (e.g. video.js, JWPlayer, etc). For example, see https://boxcast.github.io/boxcast-sdk-js/#overview
Building a custom OTT app, or integrating BoxCast broadcasts into an existing OTT app (e.g. Roku, FireTV, etc)
BoxCast API Overview
The BoxCast API exists to provide partners and broadcasters with programmatic access to BoxCast's services, including scheduling broadcasts, managing channels, embedding video players, consuming viewer analytics, etc. In general, anything that a broadcaster can accomplish through the BoxCast web dashboard can be accomplished directly through the API.
There are 4 different BoxCast authentication mechanisms supported by the BoxCast API:
Public for read-only access to channels and public broadcasts
Client Credentials for individual account access only via a secure client (such as the account owner's server)
Authorization Code exchange with a secure client (such as a 3rd party app with a secure server)
Authorization Code plus PKCE with a public client (such as a mobile app or SPA with no secure server)
Answer a few questions to see if this article is for you
Do you want to schedule broadcasts automatically or edit/create/delete any other BoxCast information as part of your integration?
If so, you cannot use the public API, so this article is not intended for your use case.
Are you trying to access BoxCast accounts that you do not own the rights to?
If so, you cannot use the public API, so this article is not intended for your use case.
Do you access any BoxCast resources other than Channels and Broadcasts?
If so, you cannot use the public API, so this article is not intended for your use case.
Getting Started with the BoxCast Public API
BoxCast supports public authentication on GET requests to certain resources. The data returned is limited to non-sensitive information, and a known Account, Channel, or Broadcast ID is required in order to access each resource. With public authentication, you can simply query the API resource with no Authorization header or token required. Any active account is able to use the Public API.
There are multiple SDKs available to guide your implementation depending on your language of choice. The SDKs will help with listing and watching broadcasts in your various account channels. You are strongly encouraged to use one of the following SDKs rather than building your own:
Finding Your Channel ID
You can find your account and channel IDs on the BoxCast Dashboard. Simply visit the Settings page of the Dashboard and look for your Account ID and Channel ID:
If you create custom channel(s), each one will be assigned a unique ID as well. Those Channel IDs can be found in the Channel Settings dialog, under the Advanced tab.
Public API Resource Endpoints
Channel Broadcasts
You can query for all broadcasts in a given channel using the following endpoint:
https://api.boxcast.com/channels/{channel_id}/broadcasts
Parameters:
q - search query (e.g. "timeframe:current")
p - page number (default 1)
l - page size limit (default 20)
s - sort (e.g. "-starts_at")
See Also:
Broadcast Details
To retrieve additional fields on the broadcast beyond what the channel-broadcast list response provides, you can query for broadcast details using the following endpoint:
https://api.boxcast.com/broadcasts/{broadcast_id}
Notes:
The response here does not provide a playable media file. In order to watch the broadcast, you will need to either (a) Embed the BoxCast Player, (b) Integrate a supported BoxCast SDK, or (c) build your own video player integration.
Embedded Video Player Documentation
Broadcast View
CAUTION: Before you attempt to use a custom video player using this route, please try to use one of the supported BoxCast SDKs or request assistance from BoxCast. This will provide the greatest playback quality, reliability, and allows for proper tracking of viewer analytics so you can better support and understand your audience. The SDKs also afford easier integration by simply requesting the playback of a given broadcast rather than manually looking up the playlist and processing the various states.
The broadcast "view" is required in order to access the HLS playlist (M3U8) for a given broadcast. It can be found by querying the following endpoint:
https://api.boxcast.com/broadcasts/{broadcast_id}/view
Parameters:
channel_id - ID of the channel for how the broadcast was accessed. If accessed directly, this can be broadcast.channel_id
host - hostname of current site accessing route
extended - "true" to allow live DVR
byteranges - "true" to allow the lower latency byterange playlist
Notes About Response Fields:
status: if everything is good to go, this string will contain either the word "live" or "recorded". There are other states such as "upcoming" or "preparing" or "stalled" that might indicate a problem, and there is a small period of time where it goes to "processing_recording" between live and on-demand windows.
playlist: this will either be blank or contain a m3u8 URL ... as long as status is "live" or "recorded", the m3u8 will be playable. Note that the playlist will change from when it is live to when it is recorded.
progress: integer field 0-100 that reports a percentage on certain statuses (such as processing_recording, or preparing). You can just ignore it for your use-case.
settings: this is a JSON object that is the amalgamation of account.content_settings, channel.content_settings, and broadcast.content_settings. Certain properties are read from here such as public account preferences and other broadcast settings that you might want to use in the future. For now, you can probably ignore it, but it's a way to share information that you can attach to a broadcast in user-scope and allow it to be used from your player.