Skip to main content

Making Requests

The calls to the API must be made in the form of HTTP requests using GET, POST, or DELETE to the domain api.betaseries.com, for example:

GET https://api.betaseries.com/shows/display?id=1

The API server is also accessible via HTTPS, and this protocol should be preferred if possible.

The return format can be either JSON or JSONP, which generally looks like this:

{
    ( ... response ... )
    "errors": []
}

If you add a jsonp parameter to your HTTP request, the JSON is transformed into JSONP:

callback(( ... response ... ), "errors":[]}})

If there are no errors, the HTTP return code is the standard 200. In case of an error, a 400 code is returned, and the information is in the errors array.

Mandatory parameters​

API Version​

All requests must have the version parameter set to at least 3.0 to use this API.

?v=

You can also specify an HTTP header instead of the parameter:

X-BetaSeries-Version:

The current version is above. For more information, see the version details.

API Key​

For all your requests, you must mention your API key in the request:

Either with the key parameter:

?key=<key>

Or in the HTTP header:

X-BetaSeries-Key: <key>

This parameter is mandatory to prevent potential abuse of the API.

Member Token​

When you need to interact with a member account, you must first identify this member with the /members/auth or /members/oauth function. Once identified, you retrieve a token that you will use in all subsequent requests:

Either to be placed as a parameter:

?access_token=<token>

Or in the HTTP header:

Authorization: Bearer <token>

You can destroy the token at any time using /member/destroy.

User-Agent​

It is recommended to specify a User-Agent specific to your application in your requests. This way, if you use your key for multiple applications, it will be easier for us to differentiate your traffic.

Field Parameter​

On methods updated since version 3.0, it is possible to select the fields of the returned object by specifying the fields parameter.

GET https://api.betaseries.com/shows/list?fields=id,title,images.poster

In this example, we retrieve three fields id, title, and images.poster per returned element in shows:

{
    "shows": [
        {
            "id": 7719,
            "title": "Better Call Saul",
            "images": {
                "poster": "https://storage.sbg.cloud.ovh.net/v1/AUTH_5960bac2938641b48bbb3d76e4509d12/pictures/fonds/poster/273181.jpg"
            }
        }
    ],
    "errors": []
}

This allows you to limit the bandwidth used and optimize your use of the API.