Overview

Media Types

The Cablecast API supports two media types, application/json and application/xml. The type of response is determined by the Accepts HTTP header. When performing a POST or PUTrequest theContent-Type HTTP header should be set to the media type of the payload.

Response Structure & Sideloading

The Cablecast API places all resources in a single root object for application/json and application/xml media types. Endpoints that support a single resource, such as POST and PUT, will use the singular form of the resource as a property of the root to transmit the resouce. Endpoints that support a collection of resources, such as GET, will use the plural form of the resouce as a property of the root to transmit the resource.

Some endpoints support sideloading related resouces by specifying an include query parameter. The include parameter should be provided as a comma seperted list of singular resources.

The following example shows what a POST request for a Category would look like. Notice the signluar Category property contained within the root.

        {
          category: {
            name: 'Category Name'
          }
        }
        

The following example shows the response for a GET request for shows using the URL /cablecastapi/v1/shows?include=reel,media. Notice the reels and media collections of sideloaded with the shows collection.

        {
          shows: [
            {
              id: 1,
              title: 'An Awesome Show'
            }
          ],
          reels: [
            {
              id: 99,
              showId: 1,
              length: 200
              media: 9999
            }
          ],
          media: [
            {
              id: 9999,
              name: 'An Awesome Media'
            }
          ]
        }
        

Pagination

Endpoints that are expected to expose a large collection of resources such as shows, scheduleitems, vods, and digitalfiles return paginated results. These endpoints support two query paramters to control the paginated results. The offset query parameter specifies the index at which the results will begin. The page_size query parameter specifies the number of results that will be returned.

Paginated endpoints return a meta property in the response payload with three properties. The offset and pageSize properites correspond to the query paramters provided to the request. (If no query paramters are provided, the meta object will represent the default values for that endpoint.) Additionaly, meta contains a count property which indicates how many total results are available on the server for the current paginated result set. An example of the meta property is provided below. The example indcates that the current results included results 23 through 43 and that there are 199 results available on the server.

        {
          meta: {
            offset: 23,
            pageSize: 20,
            count: 199
          }
        }
        

Authentication

All endpoints that create, update, or delete record as well as endpoints that allow reading sensitive methods require authentication. If no authentication is provided, the request will error with a 401 un-authorized status code. Authorization can be provided in two ways, described below.

Cookie Based Authentication

The Cablecast API will authenticate requests that contain a cookie linking the request to an active Frontdoor session. This authentication method should be used by applications that run along side the Cablecast web interface such as Plugins. All other applications should use HTTP Basic Authentication described next.

HTTP Basic Authentication

The Cablecast API will authenticate requests that provide a valid Authorization header using valid Frontdoor credentials. For more information on basic authentication see: https://en.wikipedia.org/wiki/Basic_access_authentication.

Caching

To provide the best possible performance for common use cases, the Cablecast API will cache anonymous requests for several minutes. It is recommended that clients respect the Cache-Control response headers. If un-cached content is required, the request should be authenticated.

Cross Origin Resource Sharing (CORS)

The Cablecast API is configured, by default, to allow Cross Origin Resource Sharing among all domains for read only GET requests. This will allow the Cablecast API to be accessed via Javascript from modern web browsers. If modification is required, the CORS headers can be changed by editing the Web.config located in the CablecastAPI web directory on the Cablecast server. Below is the default configuration for the CablecastAPI. For more on CORS see https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

        <system.webServer>
            <httpProtocol>
                <customHeaders>
                    <add name="Access-Control-Allow-Origin" value="*" />
                    <add name="Access-Control-Allow-Methods" value="GET,HEAD"/>
                    <add name="Access-Control-Allow-Headers" value="Content-Type" />
                </customHeaders>
            </httpProtocol>
        </system.webServer>
        

Versioning & Compatibility

There are two version numbers when interacting with the Cablecast API.

The first version number is the Cablecast version number which can be obtained programmatically using the SystemInfo endpoint. This version number can be used to ensure that the Cablecast server is compatible with the version required. It is recommended that clients confirm the Cablecast version required when accessing the Cablecast API.

The second version number is the Cablecast API version which is currently v1. The Cablecast API version will only be incremented if breaking changes are introduced to the API, meaning that an endpoint or model property has changed or been removed. Additions to the API, including new endpoints, models, or properties do not cause an increment in the API version. Therefore, it is important that clients be resilient to additional properties in request payloads. It is recommended to only rely on properties needed by the client application, not exact schemas.

When a breaking changed is introduced to the Cablecast API, necessitating a new Cablecast API version, the depreciated endpoints will still be made available for at least one Cablecast release cycle. During this time the depreciated endpoints will include an additional Warning header indicating the endpoint has been deprecated. It is recommended that clients monitor for the Warning header and alert users for the need to update the client.

Questions & Sample Code

The Cablecast Engineering Team has created an open source repository on Github to host sample code and more concrete examples of working with the Cablecast API than this documentation can provide. http://cablecast-api-examples.trms.com/ will be updated with example code as developers work with the API. If you have specific questions on how to work with the API, please create an issue on the Cablecast API Examples repository.

Another excellent resource for exploring what is possible

Endpoints

Blocks

The blocks endpoint gives access to the Block model. This endpoint is not paginated.

Describes Block
APIDescription
GET v1/blocks

Retrieve all blocks. This resource is not paginated.

GET v1/blocks/{id}

Retrieves a single Block by ID.

POST v1/blocks

Creates a new Block.

PUT v1/blocks/{id}

Updates an existing Block.

DELETE v1/blocks/{id}

Deletes a Block.

Categories

The Categories endpoint gives access to the Category model. This endpoint is not paginated.

Describes Category
APIDescription
GET v1/categories

Retrieves all Categories.

GET v1/categories/{id}

Retrieves a single Category by ID.

PUT v1/categories/{id}

Updates an existing Category.

POST v1/categories

Creates a new Category.

DELETE v1/categories/{id}

Deletes a Category.

Channels

The Channels endpoint gives access to the Channel model. This endpoint is not paginated.

Describes Channel
APIDescription
GET v1/channels

Retrieves all channels.

GET v1/channels/{id}

Retrieves a single Channel by ID.

PUT v1/channels/{id}

Updates an existing Channel.

DELETE v1/channels/{id}

Deletes a Channel.

POST v1/channels

Creates a new Channel.

Chapter

Describes Chapter
APIDescription
GET v1/chapters

Retrieve all Chapters.

GET v1/chapters/{id}

Retrieve a single Chapter by ID.

PUT v1/chapters/{id}

Update an existing Chapter.

POST v1/chapters

Creates a new Chapter.

CrawlEvents

CrawlEvents define the attributes of the crawl being run.

Describes CrawlEvent
APIDescription
GET v1/crawlevents

This returns a paginated list of all of the CrawlEvents for a specific Channel.

GET v1/crawlevents/{id}

Returns a specific CrawlEvent specified by ID

POST v1/crawlevents

Create a new CrawlEvent by sending the new resource.

PUT v1/crawlevents/{id}

Update an existing CrawlEvent record.

PUT v1/crawlevents/batch

Updates a collection of crawl events.

POST v1/crawlevents/batch

Updates a collection of crawl events.

CustomFields

CustomFields describe properties Custom1 through Custom8 on the Show Model. Note: CustomFields may change in the near future. Unless your application needs access to CustomFields for its functionality, it's best to avoid accessing them.

Describes CustomField
APIDescription
GET v1/customfields

Retrieves all CustomFields

GET v1/customfields/{id}

Retrieve a single CustomField by ID.

DigitalFiles

Describes DigitalFile
APIDescription
GET v1/digitalfiles

Retrive all DigitalFiles.

GET v1/digitalfiles/{id}

Retrieve a single DigitalFile by ID.

POST v1/digitalfiles/{id}/rename

Renames a DigitalFile.

POST v1/digitalfiles/{id}/reindex

Adds a DigitalFile to the reindexing queue.

DELETE v1/digitalfiles/{id}

Deletes a DigitalFile. Note: This method deletes the file on disk!

Dispositions

Describes Disposition
APIDescription
GET v1/dispositions

Retrieve all Dispositions.

GET v1/dispositions/{id}

Retrieve a single Disposition by ID.

Events

Describes Event
APIDescription
GET v1/events

Retrieve all Events.

GET v1/events/{id}

Retrieve a single Event by ID.

EventSummaries

Event Summaries proide a quick view of the events.

APIDescription
GET v1/eventsummaries

Get a list of all Event Summaries

Feeders

Feeders are a video output router. Given a specific location and input, the signal can be directed to an output.

Describes Feeder
APIDescription
GET v1/feeders

Return a list of all Feeders.

FirstRuns

APIDescription
GET v1/firstruns

GET v1/firstruns/{id}

Formats

Describes Format
APIDescription
GET v1/formats

Retrieve all Formats.

GET v1/formats/{id}

Retrieve a specific Format

IFrames

Describes IFrame
APIDescription
GET v1/iframes

Retrieves all IFrames

GET v1/iframes/{id}

Retrieve a specific IFrame by id.

LiveStreamQualities

Describes LiveStreamQuality
APIDescription
GET v1/livestreamqualities

Retrieve all LiveStreamQualities

GET v1/livestreamqualities/{id}

Retrieve a specific LiveStreamQuality by ID.

LiveStreams

Describes LiveStream LiveStreamConfiguration
APIDescription
GET v1/livestreams

Retrieve all LiveStreams.

GET v1/livestreams/{id}

Retrieve a specific LiveStream by ID.

GET v1/livestreamconfigurations/{id}

Retrieve a LiveStream Configuration by ID.

PUT v1/livestreams/{id}

Update an existing LiveStream

POST v1/livestreams

Create a new LiveStream

DELETE v1/livestreams/{id}

Deletes a LiveStream by ID.

PUT v1/livestreams/{id}/state

Change the state of the LiveStream. Valid State values are "START_PENDING" and "STOP_PENDING"

GET v1/livestreams/{id}/status

Get current status of LiveStream.

GET v1/livestreams/{id}/metrics

Locations

Describes Location
APIDescription
GET v1/locations

Retrieve all Locations.

GET v1/locations/{id}

Retrieve a specific Location by ID.

ManualEvents

View and manage manually scheduled events (show runs).

Describes
APIDescription
GET v1/manualevents

List all ManualEvents. Internally limited results unless overriden by the given parameters. This endpoint is paginated.

GET v1/manualevents/{id}

Return a specific ManualEvent by given ID.

PUT v1/manualevents/{id}

Update an existing ManualEvent.

POST v1/manualevents

Create a new ManualEvent.

PUT v1/manualevents/batch

Updates a collection of manual events.

POST v1/manualevents/batch

Updates a collection of manual events.

Media

Describes Media
APIDescription
GET v1/media

Retrieve all Media.

GET v1/media/{id}

Retrieve a specific Media by ID.

PUT v1/media/{id}

Update an existing Media.

POST v1/media

Create a new Media.

DELETE v1/media/{id}

Delete a Media record by ID.

Outputs

Describes Output
APIDescription
GET v1/outputs

Return a list of all Outputs available.

GET v1/outputs/{id}

Retrieve a specific Output by ID.

Plugins

Get a list of all currently installed/active Plugins.

APIDescription
GET v1/plugins

Get a list of all currently installed/active Plugins.

GET v1/plugins/{id}

Get a specific Plugin by given ID.

Producers

Describes Producer
APIDescription
GET v1/producers

Retrieve all Producers.

GET v1/producers/{id}

Retrieve a specific Producer by ID.

PUT v1/producers/{id}

Update an existing Producer.

POST v1/producers

Create a new Producer record.

DELETE v1/producers/{id}

Delete a Producer record

Projects

Describes Project
APIDescription
GET v1/projects

Retrieve all Projects.

GET v1/projects/{id}

Retrieve a single Project.

PUT v1/projects/{id}

Update an existing Project.

POST v1/projects

Create a new Project.

DELETE v1/projects/{id}

Delete a Project.

PublicSites

Describes PublicSite
APIDescription
GET v1/publicsites

Retrieve all Public Sites.

GET v1/publicsites/{id}

Retrieve a single Public Site Configuration by Id.

PUT v1/publicsites/{id}

Update an existing PublicSite.

RaidInfos

Get info about RAID status.

Describes RaidInfo
APIDescription
GET v1/raidinfos

Get a list of all RAID statuses.

GET v1/raidinfos/{id}

Get a specific RAID status by given ID.

RecordEvents

Manage and update all RecordEvents.

Describes RecordEvent
APIDescription
GET v1/recordevents

Get a list of all record events. This endpoint is paginated.

GET v1/recordevents/{id}

Get a specific RecordEvent by given ID.

PUT v1/recordevents/{id}

Update an existing RecordEvent.

POST v1/recordevents

Create a new RecordEvent.

Reels

Describes Reel
APIDescription
GET v1/reels

Retrieve all Reels.

GET v1/reels/{id}

Retrieve a single Reel by ID

PUT v1/reels/{id}

Update a Reel.

POST v1/reels

Create a new Reel.

DELETE v1/reels/{id}

Delete a Reel.

ScheduleItems

Describes ScheduleItem
APIDescription
GET v1/scheduleitems

Retrieve all ScheduleItems

GET v1/scheduleItems/{id}

Get a specific ScheduleItem.

PUT v1/scheduleitems/{id}

Update a an existing ScheduleItem.

POST v1/scheduleitems

Create a new ScheduleItem.

PUT v1/scheduleitems/batch

Updates a collection of schedule items.

POST v1/scheduleitems/batch

Updates a collection of schedule items.

Servers

Describes Server RaidInfo VolumeInfo
APIDescription
GET v1/servers

Retrieves all Servers.

GET v1/servers/{id}

Retrieve a specific Server.

PUT v1/servers/{id}

Update a Server

POST v1/servers

Create a new Server.

DELETE v1/servers/{id}

Delete a Server

GET v1/servers/{id}/connection

Test the connection to the Server.

ShowFiles

Show files are digital files that can be associated with a show.

Describes ShowFile
APIDescription
GET v1/showfiles/{id}

Get a specific ShowFile.

POST v1/showfiles

Create a new ShowFile.

PUT v1/showfiles/{id}

Update an existing ShowFile.

DELETE v1/showfiles/{id}

Delete an existing ShowFile.

SiteGalleries

APIDescription
GET v1/sitegalleries

Retrieves all site galleries.

GET v1/sitegalleries/{id}

Retrieves a single site gallery by Id.

POST v1/sitegalleries

Creates a new site gallery.

PUT v1/sitegalleries/{id}

Update an existing site gallery.

DELETE v1/sitegalleries/{id}

Delete an existing site gallery.

SystemInfo

Return an object of all of the system information such as SiteName, Licensing, etc...

APIDescription
GET v1/systeminfo

Retrieve licensing and version info.

SystemSettings

Describes SystemSettings
APIDescription
GET v1/systemsettings

Retrieve SystemSettings.

PUT v1/systemsettings

Update SystemSettings

SystemTime

SystemTime returns an accurate representation of the current time on the server as well as a client offset due to HTTP request delay.

APIDescription
GET v1/systemtime

Return the current system time. Also returns client offset given a client_time timestamp.

Thumbnails

Get thumbnail data.

Describes Thumbnail
APIDescription
GET v1/thumbnails/{id}

Get a thumbnail object by given ID.

UserSession

User sessions contain permission and user data.

APIDescription
GET v1/usersession

Get an updated UserSession object.

UserSettings

User settings are general demographic and usability information such as location, channel, name, time format, etc...

Describes UserSettings
APIDescription
GET v1/usersettings/{name}

Get the UserSettings for a user based on their username.

PUT v1/usersettings/{name}

Update a user's UserSettings.

VodConfigurations

Describes VodConfiguration
APIDescription
GET v1/vodconfigurations

Retrieve all VODConfigurations.

GET v1/vodconfigurations/{id}

Retrieve a specific VODConfiguration.

PUT v1/vodconfigurations/{id}

Update a VODConfiguration

Vods

Describes Vod
APIDescription
GET v1/vods

Retrieve All VODs

GET v1/vods/{id}

Retrieve specific VOD

GET v1/vods/{id}/chapters

Generate a WebVTT file of chapters/markers for a specific VOD

PUT v1/vods/{id}

Update an existing VOD.

POST v1/vods

Create a new VOD.

DELETE v1/vods/{id}

Delete a VOD.

GET v1/vods/stats

VodTransactions

Describes VodTransaction
APIDescription
GET v1/vodtransactions

Retrieve all VODTransactions

GET v1/vodtransactions/{id}

Retrieve a specific VODTransaction

PUT v1/vodtransactions/{id}

Update an existing VODTransaction.

POST v1/vodtransactions

Create a new VODTransaction.

VodTranscodeQualities

Describes VodTranscodeQuality
APIDescription
GET v1/vodtranscodequalities

Retrieves all VODTranscodeQualities.

GET v1/vodtranscodequalities/{id}

Retrieve a specific VODTranscodeQuality.

VolumeInfos

VolumeInfos describes a list of attached Volumes and their status. This endpoint is not paginated.

Describes VolumeInfo
APIDescription
GET v1/volumeinfos

Retreives all the VolumeInfos.

GET v1/volumeinfos/{id}

Get a specific Volume Info resource.

GET v1/volumeinfos/stats

Get a general object that represents the stats.

WebFiles

WebFiles are actual files on the system that are available to shows or other resources.

Describes WebFile
APIDescription
GET v1/webfiles/{id}

Retrieve a specific WebFile.

POST v1/webfiles/upload

Upload a specific WebFile. This endpoint accepts a file upload in the form of a media file. An ID and URL will be generated and returned. This ID can then be used to access data about the file.