BoxCast <Developer />   API Reference


Overview

Please note: This documentation currently lags the deployed API. Details are subject to change without notice.

The BoxCast API exists to provide partners and broadcasters with programmatic access to BoxCast's services, including scheduling broadcasts, embedding video players, consuming view statistics, etc. In general, anything that a broadcaster can accomplish through the BoxCast web dashboard can be accomplished directly through the API.

Endpoint Access

API requests must be encrypted via TLS/SSL. Unencrypted requests will be rejected.

All resouces are accessed relative to the API base URL:

https://api.boxcast.com/

Guiding Principles

The BoxCast API conforms to a standard HTTP REST pattern. It is organized as a set of resources that can be created, read, updated, deleted, listed and/or searched through HTTP requests. In general, snake_case is used for all resource names, parameters, field names and tokens.

In order to avoid common client bugs, the API also avoids the use of null and never omits unused fields from a response. Instead, meaningful values are returned, such as an empty string ("") or a far-future datetime ("9999-12-31T23:59:59Z") as appropriate.

The following typical patterns are used for resource requests:

HTTP Request PatternDescription
for a resource colletion
POST /resourcesCreate a new resource from the posted parameters.
GET /resources/idRead detailed information about the identified resource.
PUT /resources/idUpdate the identified resource from the posted parameters.
DELETE /resources/idDelete the identified resource.
GET /resourcesSearch and list resource summaries.
for a singleton
GET /resourceRead detailed information about the singleton resource.
PUT /resourceUpdate the singleton resource from the posted parameters.

Authentication

The BoxCast API handles authentication in conformance with the OAuth2 protocol (RFC 6749 ). One of the OAuth2 grant types (password) are used to acquire an access token. Once the API client has a valid access token, subsequent authenticated requests can be made by supplying the access token in the HTTP Authorization header as a bearer token (RFC 6750 ).

OAuth2 Authorization Endpoint
https://login.boxcast.com/oauth2/authorize
OAuth2 Token Endpoint
https://login.boxcast.com/oauth2/token

API Client Credentials

All API clients must be registered before use. Please contact BoxCast customer support to register an API client application and receive valid API client credentials.

ParameterTypeDescriptionRemarks
client_idslug The API client's primary unique identifier.Required.
client_secrettext The API client's secure password. This must be kept secure at all times.Required.

Authorization Code Grant

This type of grant allows BoxCast accounts to be safely integrated into 3rd-party web applications. For example, a website hosting company may want to allow BoxCast customers to integrate their broadcasts into their website without needing to go to the BoxCast dashboard or cut-and-paste any codes. This type of grant makes that possible, while keeping the user's BoxCast account independent from their 3rd-party (e.g. website hosting) account.

An API client authenticates by redirecting a user to BoxCast, which allows the user to login and grant access to the API client. Once the user has granted access, they are redirected to the API cient's redirection endpoint (setup during registration) along with a one-time authorization code. The API client can then send this code securely to the BoxCast API in exchange for an access token.

Step 1: The API client sends the user to BoxCast for authentication and permission

https://login.boxcast.com/oauth2/authorize?client_id={client_id}&response_type=code
ParameterTypeDescriptionRemarks
response_typetoken Must be "code".Required.
client_idslug The API client's unqiue identifier.Required.
stateslug An opaque value used to maintain state between the request and callback. It should be used for preventing cross-site request forgery.Optional.

Example

GET https://login.boxcast.com/oauth2/authorize?
    response_type=code&client_id=4pQPM2O6hK&state=ap24Gk

Response

200 OK
<html>...omitted...<html>

Step 2: The user logs in to BoxCast and grants permission to the API client

This is all handled on the BoxCast site.

Step 3: BoxCast redirects the user back to the API client with an authorization code

After authenticating the user's credentials and verifying permissions, the user is redirected back to the API client via a secure callback URI that was set during client registration. The authorization response redirects to this callback with the response parameters in the query string.

302 Found
Location: {callback_uri}?code={code}&state={state}
Response FieldTypeDescription
codeslug A one-time use authorization code which can be securely exchanged for an access token.
stateslug The exact same value that was passed in the initial request. API clients should use this to match callbacks to requests and reject any callbacks that are not matched.

NOTE: If there is a problem, then the callback URI will not receive an authorization code, but error fields instead.

Step 4: The API client exchanges the authorization code for an access token

In response, the API client should securely post this authorization code back to the token endpoint in exchange for an access token.

POST https://login.boxcast.com/oauth2/token
Authorization: Basic {base-64 endcoded client_id:client_secret}
ParameterTypeDescriptionRemarks
grant_typetoken Must be "authorization_code".Required.
codeslug The one-time authorization code returned from the authorization endpoint.Required.
Response FieldTypeDescription
token_typetoken Always "bearer".
access_tokenslug The bearer token to make authenticated requests.
expires_innumeric The number of seconds of inactivity before the token expires.

The API client can now make authenticated requets to the API.

Example

If the API client credentials are client_id=4pQPM2O6hK and client_secret=1oqZV~7.vw (and noting that the base-64 encoding of 4pQPM2O6hK:1oqZV~7.vw is NHBRUE0yTzZoSzoxb3FaVn43LnZ3), then:

POST /oauth2/tokens
Authorization: Basic NHBRUE0yTzZoSzoxb3FaVn43LnZ3
{
  "grant_type": "authorization_code",
  "code": "bDEUJZy~ISjJMlkbf.Zfks~HbDU8a0CaiQeOQyCo.QOv1HeRIW8CkFuN7dm4zYuVfw7jRfNNp~~LKClm"
}

Response

200 OK
{
  "token_type": "bearer",
  "access_token": "iq50kw1GmZ5T54PJOVpsvb5merQUwU3IT5f-Xtrxj~6jgBnwF9yCGg~zySOZ4U_ovm5wsvJkhphnDMrg",
  "expires_in": 86400
}

Password Grant

This type of grant allows BoxCast accounts to be fully controlled by a 3rd-party application. For example, a production company may wish to use BoxCast services as part of their own product. This type of grant requires the 3rd-party application to have the BoxCast user's login credentials and gives full authority to act on behalf of the BoxCast user.

An API client authenticates by directly supplying a BoxCast user's login credentials in exchange for an access token.

POST https://login.boxcast.com/oauth2/token
Authorization: Basic {base-64 endcoded client_id:client_secret}
ParameterTypeDescriptionRemarks
grant_typetoken Must be "password".Required.
usernamestring The BoxCast user's email address.Required.
passwordtext The BoxCast user's password.Required.
Response FieldTypeDescription
token_typetoken Always "bearer".
access_tokenslug The bearer token to make authenticated requests.
expires_innumeric The number of seconds of inactivity before the token expires.

The API client can now make authenticated requests to the API.

Example

If the API client credentials are client_id=4pQPM2O6hK and client_secret=1oqZV~7.vw (and noting that the base-64 encoding of 4pQPM2O6hK:1oqZV~7.vw is NHBRUE0yTzZoSzoxb3FaVn43LnZ3), then:

POST https://login.boxcast.com/oauth2/token
Authorization: Basic NHBRUE0yTzZoSzoxb3FaVn43LnZ3
{
  "grant_type": "password",
  "username": "john@example.com",
  "password": "Top53cret"
}

Response

200 OK
{
  "token_type": "bearer",
  "access_token": "iq50kw1GmZ5T54PJOVpsvb5merQUwU3IT5f-Xtrxj~6jgBnwF9yCGg~zySOZ4U_ovm5wsvJkhphnDMrg",
  "expires_in": 86400
}

Access Tokens

Once the API client has acquired an access token, it can make authenticated requests by passing it in the HTTP Authorization header as a bearer token (RFC 6750 ).

Example

GET /account
Authorization: Bearer iq50kw1GmZ5T54PJOVpsvb5merQUwU3IT5f-X
               trxj~6jgBnwF9yCGg~zySOZ4U_ovm5wsvJkhphnDMrg

Response

200 OK
{ ...omitted... }

An access token will expire after a period of inactivity. Once the token expires, it is no longer valid; any attempt to use an expired token will result in an unauthorized error.


Data Types

Data types are used by the API to validate parameters and to define possible values that a resource field may take. The following types are used:

TypeDescriptionExamples
booleanA simple true or false indicator. true, false
numericA simple number. Numeric fields may be integers, floating-point decimals, or negative numbers. A field or parameter using a numeric type may contain additional restrictions about which numbers are considered valid. 42, 3.1415, -9
textAn open text field which can contain any printable characters including newlines and whitespace. "Lorem ipsum dolor sit amet... \n
Sed ut perspiciatis... \n
At vero eos et accusamus... "
stringA single-line of text with no whitespace on either end. All printable characters are valid. "The Main Event", "Iglesia Peña", "*** The #1 Team! ***"
datetimeAn ISO 8601 formatted date/time string in UTC time. "1970-01-01T00:00:00Z", "2013-03-15T15:30:00Z", "9999-12-31T23:59:59Z"
slugA string which consists only of URL-safe characters (A-Z, a-z, 0-9, -, _, ., and ~). "n1237bc12a464", "my-widget", "-~.aFdtmXCyQkLE-uY0_"
tokenA slug which belongs to a set of possible values and has a particular meaning. Any field or parameter using a token will provide a list of possible values along with their meanings. Any value outside of the defined list is considered invalid. See BoxCaster status.
token+A token for which the set of possible values is open-ended. More values can be added to the list without changing the API version, therefore API clients are not guaranteed that the token will be from the list defined at the time that they last read the API documentation. Unknown token values must therefore be handled in a graceful way. Suggestions are provided with the specific documentation for each resource. See BoxCaster warning.
mapA map (or hash) of key-value pairs. Expected types for the map's keys and values are given in the resource field description, although each key is generally a token type. { "name": "can't be blank" }, {}, { "offset": 0, "max": 100, "count": 2 }

Requests

GET requests should pass all parameters in the URL query string.

POST and PUT requests should post all parameters in the request body using a recognized format indicated by the Content-type header. The currently supported content types for posting parameters are:

  • Content-type: application/x-www-form-urlencoded
  • Content-type: application/json


Versioning

The current API version is v1 and the only currently supported representation is JSON. These are (and will remain) the default settings.

In order to minimize API version changes, users of the API must ignore any unknown fields that are returned and handle unknown tokens gracefully (as described in each resource's reference documentation for token+ fields). When new features are added to the API, the version number will only change if the updated API would cause an existing, well-behaved client to function incorrectly.

As they become available, alternate API versions and representations can be selected using the HTTP Accept header. The currently recognized versions are:

  • Accept: application/vnd.boxcast-v1+json


Redirects

The BoxCast API may respond to any request with an HTTP redirect. An API client must follow such redirects according to the HTTP 1.1 spec by retrying the request at the URL given in the Location header. Typically, redirects will be:

HTTP StatusDescription
301The resource has been permanently moved. Future requests should be made to the new URL.
302, 307The resource has been temporarily moved. This request should be retried at the new URL, but future requests should continue to use the old URL.
304The resource has not been modified. The API client should not retry the request, but should rely on its cached copy.

Conditionals

The BoxCast API supports conditional GET requests using the HTTP headers: ETag and If-None-Match. If an API client makes a GET request, it may use the returned ETag header to make subsequent conditional GET requests for the same resource by supplying the ETag in the If-None-Match header. If the resource has not changed, the API will return a status of 304 (Not Modified) and will not count the request against the client's rate-limit.

Some resource (as noted) support conditional PUT requests using the HTTP headers: ETag and If-Match. If an API client makes a GET request, it may use the returned ETag header to make subsequent conditional PUT requests for the same resource by supplying the ETag in the If-Match header. If the resource has not changed, the API will modify the resource as requested. However, if the resource has changed, the update will fail with a status of 412 (Precondition Failed). This is very useful for making sensitive updates to avoid conflicting changes that would be unwanted.


Rate Limiting

API requests are rate limited by forbidding more than a certain number of requests in a given hour long period. If the number of allowed requests exceeds the maximum for that time period, then the request is not processed and a too_many_requests error is returned.

Authenticated API requests are limited by account to:

  • 2,000 per hour for GET requests
  • 500 per hour for POST, PUT or DELETE requests

Unauthenticated API requests are limited by IP address to:

  • 200 per hour for GET requests
  • 50 per hour for POST, PUT or DELETE requests

Each API response includes rate limiting information as extended HTTP headers:

HTTP HeaderDescription
X-RateLimit-LimitThe maximum number of requests (of this type) permitted per period.
X-RateLimit-RemainingThe number of requests (of this type) remaining in the current period.
X-RateLimit-ResetThe datetime (in UTC epoch seconds) at which the limit will reset.

Example

DELETE /broadcasts/Z7a0XjcgnYpUIuKqvxGk

Response

204 No Content
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 491
X-RateLimit-Reset: 1392228000

Pagination

API requests which search and list summaries from a resource collection are subject to pagination if there are too many results.

If a result list is paginated, the response will include an HTTP X-Pagination header, which is a JSON-encoded object that may contain the following:

KeyDescriptionExample
firstThe page number of the first page of results.
previousThe page number of the previous page of results.
nextThe page number of the next page of results.
lastThe page number of the last page of results.
totalThe total count of results.

When querying a paginated resource, the following request parameters can be provided as querystring arguments to control pagination behavior:

ParameterDescriptionExample
pThe page number to query (0-based index). p=2
lThe page size limit. l=20
sThe sort order of the results. s=-starts_at

Example

GET /broadcasts?p=2&s=-starts_at&l=20

Response

200 OK
X-Pagination: {"total":63,"first":0,"previous":1,"next":3,"last":3}
[ ...omitted... ]

Search

API requests against a resource collection support a text query syntax to narrow down and better filter results. The search is initiated by providing a string as the q querystring parameter.

The search grammar supports several types of instructions.

TypeDescriptionExample
WildcardFind partial word matches. *football*
Exact MatchFind an exact quoted string. "St. Joseph"
Field-ScopedSearch against a single field rather than all. Note that not all fields in a resource support searching against. timeframe:current
Date RangeFilter within a given set of dates. starts_at:[2015-01-01T00:00:00 TO 2015-01-02T00:00:00]
Combination (OR)Space-separated phrases are considered boolean OR. timeframe:past timeframe:current
Combination (AND)Phrases prefixed with a + are boolean AND. football +timeframe:current

Please note that if you attempt to apply a field-scoped search to a field that does not support searching, the API will return an error.


Errors

When an error occurs, the API will generally return a meaningful HTTP error code along with following error fields:

FieldTypeDescription
errortoken+ The type of error condition that occurred. Possible values are:
  • bad_request: The request could not be understood due to malformed syntax.
  • unauthorized: The request requires user authentication.
  • invalid_token: The access token provided is expired, revoked, malformed or invalid for other reasons.
  • payment_required: Payment is required to complete the request.
  • forbidden: The request is forbidden.
  • not_found: The requested resource was not found.
  • conflict: The request could not be completed due to a conflict with the current state of the resource.
  • gone: The requested resource is no longer available.
  • unprocessable_entity: The request could not be processed.
  • too_many_requests: The user has sent too many requests in a given amount of time.
  • internal_server_error: The server encountered an unexpected condition which prevented it from fulfilling the request.
  • not_implemented: The server does not support the functionality required to fulfill the request.
  • bad_gateway: The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
  • service_unavailable: The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
  • gateway_timeout: The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.
  • Other errors may be added to this list without an API version change. Therefore, API clients should treat unknown values as generic errors, relying on the HTTP error code and the error_description to handle such conditions gracefully.
When interacting with an OAuth2 endpoint, the following errors may also occur, as defined in the OAuth2 specification (RFC 6749 ):
  • invalid_request: The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
  • invalid_client: Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
  • invalid_grant: The provided authorization grant is invalid, expired or revoked.
  • unauthorized_client: The authenticated client is not authorized to use this authorization grant type.
  • unsupported_grant_type: The authorization grant type is not supported by the authorization server.
error_descriptionstring A human-friendly description of the error condition.
invalid_fieldsmap A map from field/parameter names (token+) to error descriptions (string), which provides more specific details about invalid fields or parameters.

Example

PUT /boxcasters/m9c4ebfb82112
{ "name": "" }

Response

422 Unprocessable Entity
{
  "error": "unprocessable_entity",
  "error_description": "The request could not be processed.",
  "invalid_fields": {
    "name": "can't be blank"
  }
}

Account

An account represents a person or organization that uses BoxCast services. Each account has its own boxcasters, broadcasts, users, etc. which are managed through the account and are not accessible from any other account. An account is the entity which is responsible for paying invoices or receiving profits from ticket sales.

FieldTypeDescription
idslug The primary unique identifier.
namestring A human-friendly name for quick identification and display in user interfaces.
channel_idslug An automatically created channel for all non-private broadcasts that have streamed, are streaming or will stream from the account.
descriptiontext A description of the account which is show to viewers. This text identifies and describes the organization that is providing broadcasts.
time_zonestring The primary time zone in which the organization is based.

Get Account Detail

Returns all fields for the current account.

GET /account

Example

GET /account

Response

200 OK
{
  "id": "MTVUYQLN",
  "name": "The Ocho",
  "channel_id": "3nRUBPr00vqUSYYKfBtX",
  "description": "The obscure sports network.",
  "time_zone": "Pacific Time (US & Canada)"
}

BoxCasters

A BoxCaster is a device that captures, encodes, and transmits an audio/video stream to the BoxCast service over a network.

FieldTypeDescription
idslug The primary unique identifier. Usually, this ID is printed on the underside of the BoxCaster device.
namestring A human-friendly name for quick identification and display in user interfaces.
statustoken An indicator of the current state of the BoxCaster:
  • offline: It has not reported to the BoxCast service for long enough that it is assumed to be powered off or disconnected from the network.
  • ready: It is online and waiting for the next scheduled broadcast.
  • preparing_broadcast: It is preparing for a scheduled broadcast which will be starting soon. Preparation includes finding a valid audio/video source, determining network connection speeds, allocating resources through the BoxCast service and communicating all necessary configuration parameters.
  • broadcasting: It is actively capturing, encoding and transmitting an audio/video stream through the BoxCast service.
warningtoken+ An indicator of any warning condition that the BoxCaster has detected:
  • none: It has no warnings to report.
  • no_video_source: It was preparing a broadcast, but was unable to detect a valid audio/video source. This must be resolved before the BoxCaster can finish preparations and begin broadcasting.
  • updating_firmware: It received a firmware update from the BoxCast service and is updating itself. This only occurs when there are no broadcasts scheduled in the near future. The BoxCaster should not be powered off or disconnected from the network until the firmware update is complete.
  • Other warnings may be added to this list without an API version change. Therefore, API clients should handle an unknown warning gracefully. Generally, a warning when the BoxCaster is offline or ready does not require any immediate action, but a warning that occurs while the BoxCaster is preparing_broadcast or broadcasting indicates a problem with a live stream and will need to be resolved quickly to avoid broadcast failure.
last_seen_atdatetime The last time at which the BoxCaster reported to the BoxCast service. This is helpful information when the BoxCaster is offline.
next_broadcast_atdatetime The start time of the next broadcast that the BoxCaster will need to stream (or of the currently streaming broadcast). This is helpful information when the BoxCaster has an unexpected status, such as being offline during a scheduled broadcast. If there is no upcoming broadcast scheduled on the BoxCaster, then this field will show a far-future date (e.g., 9999-12-31T23:59:59Z).
next_broadcast_idslug The ID of the next broadcast that the BoxCaster will need to stream (or of the currently streaming broadcast). If there is no upcoming broadcast scheduled on the BoxCaster, then this field will be blank.
next_broadcast_namestring The name of the next broadcast that the BoxCaster will need to stream (or of the currently streaming broadcast). If there is no upcoming broadcast scheduled on the BoxCaster, then this field will be blank.
the following fields are excluded from summary responses
channel_idslug An automatically created channel for all non-private broadcasts that have streamed, are streaming or will stream through the BoxCaster.

Get BoxCaster Detail

Returns all fields for the specified BoxCaster.

GET /boxcasters/{id}

Example

GET /boxcasters/m9c4ebfb82112

Response

200 OK
{
  "id": "m9c4ebfb82112",
  "name": "Main Camera",
  "status": "broadcasting",
  "warning": "none",
  "last_seen_at": "2012-10-09T15:44:09Z",
  "next_broadcast_at": "2012-10-09T15:00:00Z",
  "next_broadcast_id": "e3u2Te__7aaAqUNkjvpj",
  "next_broadcast_name": "Smith Wedding 10/9/12",
  "channel_id": "dSUdyxXH1loPJYIlR4F0"
}

Update a BoxCaster

Updates the supplied fields of the specified BoxCaster.

PUT /boxcasters/{id}
ParameterTypeDescriptionRemarks
namestring The desired name for the BoxCaster.Optional.

Example

PUT /boxcasters/m9c4ebfb82112
{ "name": "New Name" }

Response

200 OK
{
  "id": "m9c4ebfb82112",
  "name": "New Name",
  "status": "broadcasting",
  "warning": "none",
  "last_seen_at": "2012-10-09T15:44:09Z",
  "next_broadcast_at": "2012-10-09T15:00:00Z",
  "next_broadcast_id": "e3u2Te__7aaAqUNkjvpj",
  "next_broadcast_name": "Smith Wedding 10/9/12",
  "channel_id": "dSUdyxXH1loPJYIlR4F0"
}

List BoxCasters

Returns summary fields for all BoxCasters on the current account.

GET /boxcasters

Example

GET /boxcasters

Response

200 OK
[
  {
    "id": "m9c4ebfb82112",
    "name": "Main Camera",
    "status": "broadcasting",
    "warning": "none",
    "last_seen_at": "2012-10-09T15:44:09Z",
    "next_broadcast_at": "2012-10-09T15:00:00Z",
    "next_broadcast_id": "e3u2Te__7aaAqUNkjvpj",
    "next_broadcast_name": "Smith Wedding 10/9/12"
  }, {
    "id": "m9c4ebf96d67a",
    "name": "Mobile Camera",
    "status": "ready",
    "warning": "updating_firmware",
    "last_seen_at": "2012-10-09T15:44:17Z",
    "next_broadcast_at": "2012-10-21T10:30:00Z",
    "next_broadcast_id": "wiY7AZb5oA1U52u0mX8k",
    "next_broadcast_name": "First Service"
  }
]

Broadcasts

A broadcast represents a single audio/video stream with a name, description and start/stop times. A broadcast is always streamed through a specific BoxCaster, and it may have a live stream or recording associated with it or it may be a mere placeholder (i.e. if it is scheduled to start in the future).

FieldTypeDescription
idslug The primary unique identifier.
namestring A human-friendly name for quick identification and display in user interfaces.
channel_idslug An automatically created channel which consists only of this broadcast (even if the broadcast is private).
previewstring A URL to a thumbnail image for the broadcast, if available.
stream_sourcetoken The source of the audio and video for the broadcast:
  • boxcaster: Streamed from a BoxCaster.
  • app: Streamed from the Broadcaster app for iOS.
  • switcher: Streamed from the BoxCaster Switcher app for iOS.
  • rtmp: Streamed from an external RTMP source.
boxcaster_idslug The id of the BoxCaster that streamed or will stream the broadcast. Empty if stream_source is not boxcaster.
boxcaster_namestring The name of the BoxCaster that streamed or will stream the broadcast. Empty if stream_source is not boxcaster.
starts_atdatetime The scheduled start time for the broadcast.
stops_atdatetime The scheduled stop time for the broadcast.
timeframetoken An indicator of the timeframe in which this broadcast is scheduled to stream:
  • future: The broadcast is scheduled to stream at some time in the future.
  • preroll: The broadcast is scheduled to start streaming very soon and is preparing now.
  • current: The broadcast is currently scheduled to be streaming now.
  • past: The broadcast was scheduled to stream at some time in the past.
is_privateboolean A public broadcast may be listed and promoted by BoxCast so that a public viewer can find it easily. If a broadcast is private, however, then BoxCast will generate an obfuscated channel for the broadcast and will not promote it or list it in any channels (except for its own channel). This is useful, for example, when creating a test broadcast.
is_ticketedboolean A ticketed broadcast requires a ticket purchase to view the full stream. Some ticketed broadcasts offer a variant stream which is viewable without a ticket purchase (so-called "flex" broadcasts).
ticket_pricenumeric The purchase price in USD for a ticket to view the highest quality version of the broadcast. All values are rounded to two decimal places.
free_varianttoken+ A variant of the broadcast which may be viewed without purchasing a ticket:
  • none: There is no free variant; the stream can only be viewed by purchasing a ticket.
  • best: All variants are free; there is no need to purchase a ticket to view the stream.
  • low: A lower quality (SD-only) variant of the stream is available for free viewing.
  • audio: An audio-only variant of the stream is available for free listening.
  • Other variants may be added to this list without an API version change. Therefore, API clients should handle an unknown variant gracefully.
viewer_urlstring The URL at which BoxCast hosts a web page for viewers to watch the broadcast live or recorded.
total_view_countnumeric The total number of times this broadcast was watched.
total_minutes_viewednumeric The total duration in minutes that this broadcast was watched, across all views.
total_active_viewer_countnumeric The total number of currently active viewers of this broadcast.
the following fields are excluded from summary responses
descriptiontext Additional information to display to viewers about the broadcast.

Schedule a Broadcast

Creates a new scheduled broadcast from the supplied fields.

POST /broadcasts
ParameterTypeDescriptionRemarks
namestring The desired name for the broadcast.Required.
stream_sourceslug The source of the audio and video for the broadcast. Typically this is boxcaster.Required.
boxcaster_idslug The id of the BoxCaster that will stream this broadcast.Required if stream_source is boxcaster.
starts_atdatetime The desired starts_at for the broadcast.Required; can't be in the past.
stops_atdatetime The desired stops_at for the broadcast.Required; must be after starts_at.
is_privateboolean Whether or not the broadcast should be private.Optional.
is_ticketedboolean Whether or not the broadcast should be ticketed.Optional.
ticket_pricenumeric The desired ticket_price for the broadcast (ignored if not ticketed).Optional.
free_varianttoken+ The desired free_variant for the broadcast (ignored if not ticketed).Optional.
descriptiontext The desired description for the broadcast.Optional.

Example

POST /broadcasts
{
  "name": "Celtics vs Knicks",
  "stream_source": "boxcaster",
  "boxcaster_id": "n9c4ebf123456",
  "starts_at": "2013-04-28T23:00:00Z",
  "stops_at": "2013-04-29T02:00:00Z"
}

Response

200 OK
{
  "id": "Z7a0XjcgnYpUIuKqvxGk",
  "name": "Celtics vs Knicks",
  "channel_id": "celtics-vs-knicks",
  "stream_source": "boxcaster",
  "boxcaster_id": "n9c4ebf123456",
  "boxcaster_name": "Main Camera",
  "starts_at": "2013-04-28T23:00:00Z",
  "stops_at": "2013-04-29T02:00:00Z",
  "timeframe": "future",
  "is_private": false,
  "is_ticketed": false,
  "ticket_price": 0,
  "free_variant": "best",
  "viewer_url": "https://www.boxcast.com/show/#/celtics-vs-knicks",
  "description": ""
}

Get Broadcast Detail

Returns all fields for the specified broadcast.

GET /broadcasts/{id}

Example

GET /broadcasts/Z7a0XjcgnYpUIuKqvxGk

Response

200 OK
{
  "id": "Z7a0XjcgnYpUIuKqvxGk",
  "name": "Celtics vs Knicks",
  "channel_id": "celtics-vs-knicks",
  "boxcaster_id": "m9c4ebfb82112",
  "boxcaster_name": "Main Camera",
  "starts_at": "2013-04-28T23:00:00Z",
  "stops_at": "2013-04-29T02:00:00Z",
  "timeframe": "future",
  "is_private": false,
  "is_ticketed": true,
  "ticket_price": 5.95,
  "free_variant": "low",
  "viewer_url": "https://www.boxcast.com/show/#/celtics-vs-knicks",
  "description": "Lorem ipsum dolor sit..."
}

Update a Broadcast

Updates the supplied fields of the specified broadcast.

PUT /broadcasts/{id}
ParameterTypeDescriptionRemarks
namestring The desired name for the broadcast.Optional.
boxcaster_idslug The id of the BoxCaster that will stream this broadcast.Optional.
starts_atdatetime The desired starts_at for the broadcast.Optional; can't be in the past.
stops_atdatetime The desired stops_at for the broadcast.Optional; must be after starts_at.
is_privateboolean Whether or not the broadcast should be private.Optional.
is_ticketedboolean Whether or not the broadcast should be ticketed.Optional.
ticket_pricenumeric The desired ticket_price for the broadcast (ignored if not ticketed).Optional.
free_varianttoken+ The desired free_variant for the broadcast (ignored if not ticketed).Optional.
descriptiontext The desired description for the broadcast.Optional.
WARNING: If boxcaster_id, starts_at or stops_at is changed on a broadcast that is streaming or has already streamed and the changes cause the stream to restart, the original stream/recording will be overwritten and lost. For example, if a broadcast is streaming from the wrong boxcaster and it is then updated with a new boxcaster_id, the original stream will close and a new one will open from the newly selected boxcaster; any recording from the first stream will be lost.
WARNING: Be especially careful about changing stops_at near the end of a scheduled broadcast. If the stream closes before the update request, then the update request will cause a new stream to start overwriting the original stream, which will then be lost. It is recommended to use a conditional put request to prevent this from happening.

Example

PUT /broadcasts/Z7a0XjcgnYpUIuKqvxGk
{
  "name": "The Big Game",
  "description": "This is a really big deal."
}

Response

200 OK
{
  "id": "Z7a0XjcgnYpUIuKqvxGk",
  "name": "The Big Game",
  "channel_id": "celtics-vs-knicks",
  "boxcaster_id": "m9c4ebfb82112",
  "boxcaster_name": "Main Camera",
  "starts_at": "2013-04-28T23:00:00Z",
  "stops_at": "2013-04-29T02:00:00Z",
  "timeframe": "future",
  "is_private": false,
  "is_ticketed": true,
  "ticket_price": 5.95,
  "free_variant": "low",
  "viewer_url": "https://www.boxcast.com/show/#/celtics-vs-knicks",
  "description": "This is a really big deal."
}

List Broadcasts

Returns summary fields for all broadcasts on the current account. Please be aware that the results may be paginated.

GET /broadcasts
ParameterTypeDescriptionRemarks
qstring Search query.Optional.
pstring Page number.Optional.
lstring Page size limit.Optional.
stoken Sort order.Optional.

Example

GET /broadcasts

Response

200 OK
[
  {
    "id": "Z7a0XjcgnYpUIuKqvxGk",
    "name": "Celtics vs Knicks",
    "channel_id": "celtics-vs-knicks",
    "boxcaster_id": "n9c4ebf123456",
    "boxcaster_name": "Main Camera",
    "starts_at": "2013-04-28T23:00:00Z",
    "stops_at": "2013-04-29T02:00:00Z",
    "is_private": false,
    "is_ticketed": false,
    "ticket_price": 0,
    "free_variant": "best",
    "viewer_url": "https://www.boxcast.com/show/#/celtics-vs-knicks"
  }, {
    "id": "Y9udBwPJhqZvz05xt2As",
    "name": "Internal Test",
    "channel_id": "o2Vbj5UQdNt7aq3XSW4kgRuwfyBeiG9D",
    "boxcaster_id": "n9c4ebf123456",
    "boxcaster_name": "Main Camera",
    "starts_at": "2013-04-28T21:00:00Z",
    "stops_at": "2013-04-28T21:10:00Z",
    "is_private": true,
    "is_ticketed": false,
    "ticket_price": 0,
    "free_variant": "best",
    "viewer_url": "https://www.boxcast.com/show/#/o2Vbj5UQdNt7aq3XSW4kgRuwfyBeiG9D"
  }, {
    "id": "x1LUy0tRVj9mXuOEWP7k",
    "name": "Commencement 2013",
    "channel_id": "commencement-2013",
    "boxcaster_id": "n9c4ebf123456",
    "boxcaster_name": "Main Camera",
    "starts_at": "2013-05-02T14:00:00Z",
    "stops_at": "2013-05-02T22:00:00Z",
    "is_private": false,
    "is_ticketed": true,
    "ticket_price": 5.95,
    "free_variant": "low",
    "viewer_url": "https://www.boxcast.com/show/#/commencement-2013"
  }
]

Delete a Broadcast

Deletes a broadcast from the account.

DELETE /broadcasts/{id}

Example

DELETE /broadcasts/x1LUy0tRVj9mXuOEWP7k

Response

200 OK

Channels

A channel represents a collection of broadcasts that are related in some way. It is a way for broadcasters to group and organize their content. Channels also provide an additional monetization option by allowing broadcasters to charge for collections of content.

FieldTypeDescription
idslug The primary unique identifier.
namestring The desired name for the channel.Optional.
is_ticketedboolean Whether or not the channel should be ticketed.Optional.
ticket_pricenumeric The desired ticket_price for the channel (ignored if not ticketed).Optional.
free_varianttoken+ The desired free_variant for the channel (ignored if not ticketed).Optional.

Get Channel Detail

Returns all fields for the specified channel.

GET /account/channels/{id}

Example

GET /account/channels/Z7a0XjcgnYpUIuKqvxGk

Response

200 OK
{
  "id": "Z7a0XjcgnYpUIuKqvxGk",
  "name": "2016 Basketball Season",
  "channel_id": "2016-basketball-season",
  "is_ticketed": true,
  "ticket_price": 24.95,
  "free_variant": ""
}

Update a Channel

Updates the supplied fields of the specified channel.

PUT /account/channels/{id}
ParameterTypeDescriptionRemarks
namestring The desired name for the channel.Optional.
is_ticketedboolean Whether or not the channel should be ticketed.Optional.
ticket_pricenumeric The desired ticket_price for the channel (ignored if not ticketed).Optional.
free_varianttoken+ The desired free_variant for the channel (ignored if not ticketed).Optional.

Example

PUT /account/channels/Z7a0XjcgnYpUIuKqvxGk
{
  "name": "Basketball Channel"
}

Response

200 OK
{
  "id": "Z7a0XjcgnYpUIuKqvxGk",
  "name": "Basketball Channel",
  "channel_id": "2016-basketball-season",
  "is_ticketed": true,
  "ticket_price": 24.95,
  "free_variant": ""
}

List Channels

Returns summary fields for all channels on the current account.

GET /account/channels

Example

GET /account/channels

Response

200 OK
[
  {
	"id": "Z7a0XjcgnYpUIuKqvxGk",
	"name": "Basketball Channel",
	"channel_id": "2016-basketball-season",
	"is_ticketed": true,
	"ticket_price": 24.95,
	"free_variant": ""
  }, {
	"id": "Z7a0XjcgnYpUIuKqvxGk",
	"name": "Football Channel",
	"channel_id": "2016-football-season",
	"is_ticketed": true,
	"ticket_price": 19.95,
	"free_variant": ""
  }, {
	"id": "Z7a0XjcgnYpUIuKqvxGk",
	"name": "Softball Channel",
	"channel_id": "2016-softball-season",
	"is_ticketed": false,
	"ticket_price": 0,
	"free_variant": ""
  }
]

List Channel Broadcasts

Returns minimal fields (id, name, starts_at, stops_at) for all broadcasts included in the specified channel. The list of broadcasts is presented in relevance order, meaning that broadcasts that are very recent (or coming very soon) will be listed ahead of older (or distant future) broadcasts. Any live broadcasts will be at the top of the list. Allows for the same search and pagination behavior as the top-level broadcast list query.

GET /channels/{id}/broadcasts

Example

GET /channels/dSUdyxXH1loPJYIlR4F0/broadcasts

Response

200 OK
[
  {
    "id": "Z7a0XjcgnYpUIuKqvxGk",
    "name": "Celtics vs Knicks",
    "starts_at": "2013-04-28T23:00:00Z",
    "stops_at": "2013-04-29T02:00:00Z"
  }, {
    "id": "Y9udBwPJhqZvz05xt2As",
    "name": "Internal Test",
    "starts_at": "2013-04-28T21:00:00Z",
    "stops_at": "2013-04-28T21:10:00Z"
  }, {
    "id": "x1LUy0tRVj9mXuOEWP7k",
    "name": "Commencement 2013",
    "starts_at": "2013-05-02T14:00:00Z",
    "stops_at": "2013-05-02T22:00:00Z"
  }
]

Code Samples

The following code samples are meant to help you get started using our API.

We use the following (non-functional) OAuth credentials: client ID cid1000 and secret secret9999. Once you have applied for and receieved your client ID and secret, replace the values with yours.


Exchange Authorization Code for Token

First, direct browser to https://login.boxcast.com/oauth2/authorize?client_id=cid1000&response_type=code. Then, after the user is sent back to your configured redirect URL, grab the code e.g. c123456789 from the URL.

$ export BOXCAST_CLIENT_ID=cid1000
$ export BOXCAST_SECRET=secret9999
$ export CODE_FROM_URL=c123456789

$ curl -u "${BOXCAST_CLIENT_ID}:${BOXCAST_SECRET}" \
      -d "grant_type=authorization_code" \
      -d "code=${CODE_FROM_URL}" \
      "https://login.boxcast.com/oauth2/token"

{
"token_type":"bearer",
"access_token":"YKLCJ-EJHnFXV4TThF7YNPdkyz3ia29UmCJY3vZOB",
"expires_in":604800,
"scope":"user"
}
import requests
response = requests.post('https://api.boxcast.com/oauth2/token', data={
  'grant_type': 'authorization_code',
  'code': 'c123456789'
}, auth=('cid1000', 'secret9999'))
print response.json()

{
  u'token_type': u'bearer',
  u'access_token': u'YKLCJ-EJHnFXV4TThF7YNPdkyz3ia29UmCJY3vZOB',
  u'expires_in': 604800,
  u'scope': u'user'
}
var request = require('request');
request.post({
  url: 'https://api.boxcast.com/oauth2/token',
  form: {
    grant_type: 'authorization_code',
    code: 'c123456789'
  },
  auth: {
    user: 'cid1000',
    pass: 'secret9999'
  }
}, (err, response, body) => {
  if (!err && response.statusCode == 200) {
    console.log(JSON.parse(body));
  } else {
    console.error(err, JSON.parse(body));
  }
});

You now have an access token along with the number of seconds before it expires.


Use Access Token To List 5 Broadcasts

Using the access token acquired above, you can query the rest of the BoxCast API on behalf of the authenticated user.

Here we search for broadcasts using the search filter timeframe:relevant and ask for the 1st page sorted from newest to oldest.

$ export ACCESS_TOKEN=YKLCJ-EJHnFXV4TThF7YNPdkyz3ia29UmCJY3vZOB

$ curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
       -G \
       --data-urlencode "q=timeframe:relevant" \
       --data-urlencode "s=-starts_at" \
       --data-urlencode "l=5" \
       "https://api.boxcast.com/broadcasts"

[
    {
        "admin_token": "c376bof7sbkairssvnfh",
        "boxcaster_id": "",
        "boxcaster_name": "",
        "stream_source": "app",
        "channel_id": "hockey-game-vs-st-marks-166959",
        "description": "",
        "free_variant": "best",
        "id": "1",
        "is_private": false,
        "is_ticketed": false,
        "name": "Hockey Game vs St. Marks (Audio Only)",
        "preview": "https://assets.boxcast.com/latest/static/audio-only.png",
        "requires_subscription": false,
        "starts_at": "2016-12-01T12:30:00Z",
        "stops_at": "2016-12-02T14:30:00Z",
        "tags": [],
        "ticket_price": 0,
        "total_active_viewer_count": 0,
        "total_minutes_viewed": 0,
        "total_view_count": 0,
        "transcoder_profile": "audio",
        "viewer_url": "https://boxcast.tv/view/hockey-game-vs-st-marks-166959"
    },
    ...
]
import requests
response = requests.get('https://api.boxcast.com/broadcasts', params={
  'q': 'timeframe:relevant',
  's': '-starts_at',
  'l': '5'
}, headers={'Authorization': 'Bearer YKLCJ-EJHnFXV4TThF7YNPdkyz3ia29UmCJY3vZOB'}
print response.json()


[
    {
        u'admin_token': u'c376bof7sbkairssvnfh',
        u'boxcaster_id': u'',
        u'boxcaster_name': u'',
        u'stream_source': u'app',
        u'channel_id': u'hockey-game-vs-st-marks-166959',
        u'description': u'',
        u'free_variant': u'best',
        u'id': u'1',
        u'is_private': false,
        u'is_ticketed': false,
        u'name': u'Hockey Game vs St. Marks (Audio Only)',
        u'preview': u'https://assets.boxcast.com/latest/static/audio-only.png',
        u'requires_subscription': false,
        u'starts_at': u'2016-12-01T12:30:00Z',
        u'stops_at': u'2016-12-02T14:30:00Z',
        u'tags': [],
        u'ticket_price': 0,
        u'total_active_viewer_count': 0,
        u'total_minutes_viewed': 0,
        u'total_view_count': 0,
        u'transcoder_profile': u'audio',
        u'viewer_url': u'https://boxcast.tv/view/hockey-game-vs-st-marks-166959'
    },
    ...
]
var request = require('request');
request.get({
  url: 'https://api.boxcast.com/broadcasts',
  qs: {
    q: 'timeframe:relevant',
    s: '-starts_at',
    l: '5'
  },
  auth: {
    bearer: 'YKLCJ-EJHnFXV4TThF7YNPdkyz3ia29UmCJY3vZOB'
  }
}, (err, response, body) => {
  if (!err && response.statusCode == 200) {
    console.log(JSON.parse(body));
  } else {
    console.error(err, JSON.parse(body));
  }
});