Getting StartedDiscussions

Getting Started

Suggest Edits

The Screeners API is a REST API. Getting started with it is simple.

Everything that can be done in the Screeners.com can be done using this API enabling you to build deep integrations with Screeners.com. This guide will walk you through the mechanics of using the API as well as some of the essential workflows. This site is split in to two parts: the guides (where you are now) and the API reference (where can can see the details for each endpoint).

You can interface with it using any HTTP library. Additionally, you should check out our Postman project as well as our Open API v3 Spec.

Setup

Before you can use the API you need to obtain credentials for your account. If you don't already have an account, head over to screeners.com and contact us. If you already have an account and do not have your API credentials contact us @ [email protected] and we'll get you set up. Once you have an account you can access the administration app here and the screening app here

If you're ever in need of support, find us at [email protected]

Authentication

Authenticating to the Screeners API requires an API Key and Client ID. When you make requests the the Screeners API you can include these credentials in the header like this:

x-api-key: YOUR API KEY
x-api-client-id: YOUR CLIENT ID

401

If your credentials are invalid you will receive an https status 401 in your response with a response body of:

{
    "message": "Invalid API key or client ID"
}

403

From time to time you may try to access a resource that you don't have access to. For example, it's common to be added as a viewer to a show and subsequently removed from the show after the publisher closes the viewing window. In this case, if you try to retrieve the show from the API you would receive a 403 status code in the response

Terminology

There are some conventional tasks and workflows that you should understand as you get to know the API. Before we dive right into how to implement those workflows let's go over some core terminology.

Networks

Networks represent the companies, businesses, independents, and creators that create content. In Screeners everyshow is tied to a network. Networks are branded in screeners, giving the viewers a clear way to choose what content to watch.

Shows

Shows represent a series of episodic video content. From here on let's use the fictitious show Screenerman as an example. Screenerman is widely popular and has just finished the second season and are getting ready to release their third to the press.

Episode

An episode is a single video, possibly a part of a specific season, for a given show.

Season

A season represents a specific chronological group of episodic videos.

Subtitles

For localization purposes, Screeners supports language specific subtitles

Creating Your First Show

Artwork

The first thing you need to create a show is key art. We require key art for shows in screeners because it creates a good experience for viewers. You'll need a banner image (1920x1080) and a posterframe (404x608). Both files should be publically accessible so that screeners can ingest them. To do this you could upload them to a public S3 bucket or you could use our upload API.

Creating the Show

curl -X POST \
  https://api.screeners.com/shows \
  -H 'content-type: application/json' \
  -H 'x-api-client-id: YOUR CLIENT ID' \
  -H 'x-api-key: YOUR API KEY' \
  -d '{
    "title": "Screener Man",
    "description": "Screener Man is a new superhero series",
    "posterLarge": "https://screenerman.com/3/large-poster.jpg",
    "bannerLarge": "https://screenerman.com/3/large-banner.jpg",
    "startDate": 1542380885,
    "endDate": 1514764800,
    "mfaEnabled": false,
    "facebook": "https://facebook.com/screener-man-3",
    "twitter": "https://twitter.com/screener-man-3",
    "website": "https://screenerman.com/3",
    "websiteButtonText": "Check It Out!",
    "download": false,
    "email": false
}'
Some notes:

• The posterLarge property is the posterframe we mentioned above. The bannerLarge property is the banner image we mentioned above.

• Notice that the show has a start and end date. We will only reveal the show in Screeners.com if the current date is within that window.

• You can allow or disallow users downloading content using the _download property

For full documentation on this endpoint see the API reference

Uploading Your First Episode

Artwork

Like shows, episodes also require artwork. You'll need a poster frame (1280x720). Thenposterframe should be publically accessible so that screeners can ingest it. To do this you could upload them to a public S3 bucket or you could use our upload API.

Creating the Episode

curl -X POST \
  https://api.screeners.com/shows/YOUR_SHOW_ID/episodes \
  -H 'content-type: application/json' \
  -H 'x-api-client-id: YOUR CLIENT ID' \
  -H 'x-api-key: YOUR API KEY' \
  -d '{
      "name":"Screener Man Battles the Pirates","description":"In this next episode, Screener Man fights against The Dark Legion of Pirates to protect high value content","posterLarge":"https://screenerman.com/large-poster.png",
      "season":3,
      "number":5,
      "filename":"screenerman-3-1","status":"UNPUBLISHED"}'
Some notes:

• Notice that the URL path requires a show id.

• The posterLarge property is the posterframe we mentioned above.

• The number property is the position of the episode in the season. So if this is the first episode of season 3 then number would equal 1

• Setting the status to UNPUBLISHED means that viewers cannot yet watch this episode even if the show is active.

For full documentation on this endpoint see the API reference

Updated 9 months ago