MENU
Curl Javascript

The Data API

You can incorporate the vidbeo online video platform within your own application by making use of our Data API. If you have used other APIs before, the way it works should be familiar.

If you have any questions about any of the requests, or the responses, or indeed need an endpoint that we don’t currently provide, please don’t hesitate to get in touch. We’ll do our best to help.

We recommend reading all of the information below to understand how the API is structured.

HTTP methods

Each API request uses one of the following methods. Generally (although it does depend upon what kind of action you want to perform) you will use:

Method Action
GET Used to get data about one or more resources
POST Used to create a new resource
PUT Used to update one or more attributes of a resource. Any top-level attributes not included in your request will be left unchanged
DELETE Used to delete a resource

Structure

Requests are made to a URI that follows this structure:

https://vidbeo.com/api/v1/resource/method/parameters

Make a request

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/videos/VIDEOID

You need to send two headers with each API request to identify and authenticate yourself:

The X-Auth-Email header identifies you.

The X-Auth-Key header authenticates you.

Assuming the values are valid, you should get a successful response back, since the API has been able to verify who is making the request and whether they are permitted to.

Response codes

We use the standard HTTP status codes when returning responses so that your application knows what has happened.

Code Meaning
200 The request was successful, and content is being returned. This will be the status code returned for a successful GET, PUT or POST
204 The request was successful, but no content is being returned. This will be the status code returned for a successful DELETE
400 The request was invalid. If you get this response code, the most common reason is data being sent that is invalid, which means it can not be processed. Please check that you are including all required fields and they follow the expected structure
401 The request could not be authorised. If you get this response code, please check that you are sending valid X-Auth-Email and X-Auth-Key headers
403 The request is forbidden. You are not permitted to perform the action you are trying to do using that token. If you get this response code, please check that you are accessing a resource you have been granted access to and are using https when making an authenticated reques
404 The requested resource could not be found. If you get this response code, perhaps the object has since been deleted?
429 The request could not be processed because too many requests have been made. If you get this response code, you have most likely hit our rate-limit and will need to wait for a period of time before making another request
500 There is a temporary problem with the API, which resulted in an error
503 There is a temporary problem with the API, meaning it is currently unavailable

Generally, status codes in the 2xx range mean that the request worked, status codes in the 4xx range mean that the request failed because of a problem at your end and status codes in the 5xx range mean that the request failed because of a problem at our end

Get an API key

If you have access to the ‘Account’ section of the admin panel, you should see a sub-menu within that. There is an option called ‘API’:

Create an API key

Click the button to request a new API key.

If the key is successfully created, you will be shown it. It will only be shown once so please make sure you note it before leaving the page.

Payload/response

Payloads and responses must be formatted as JSON. We recommend sending the Accept header:

Accept: application/json

We always return data using the UTF-8 character set. Any data you send to the API should also be UTF-8.

Error messages

When errors occur, in addition to the non 2xx HTTP response code, we may include a message that explains what went wrong. This will help you debug your application:

CORS

Our API supports Cross Origin Resource Sharing (CORS) for AJAX requests. A 204 code is returned in response to an OPTIONS request.

Date format

Whenever our API returns a time, it will be formatted accordingly to the internationally-agreed standard known as ISO 8601.

For example:

2018-01-01T01:00:00+00:00

Dates passed to the API as part of your request need to also follow this format.

For example:

2018-01-01

Performance

Most data does not change very often, so it makes sense to remember (at least for a short time) what our API responds with. This avoids having to repeatedly make the same request for the same data.

Saving the API response in a temporary cache within your application not only reduces the chances of hitting our rate-limits but also makes your application faster since it can proceed without having to wait for our response.

Naturally, please check the response and its code to check you are not accidentally caching an error.

Passing parameters

Some requests support being passed parameters. These are usually used to filter and/or paginate the returned data.

For GET requests, these parameters should be part of the URL and sent URL-encoded:

https://vidbeo.com/api/v1/resource/method?parameter1=value1&parameter2=value2

For POST, PUT and DELETE requests, these parameters should instead be passed within the body of the request as “raw” data. You should send a Content-Type header to specify the type of data being sent, since we may add support for alternative types. However since we currently only support JSON, we will assume application/json if this header is not passed.

This will become clearer once you see some example requests being made of this kind.

Pagination

If a large number of items need to be returned, to reduce bandwidth the API may only return a subset of the available results. Each subset is returned in a page. If there are more items in the result set than would fit within the page, multiple pages will need to be requested to return the entire result set.

The first page (the default if none is specified) is page zero (since the index starts at 0, in common with most programming). That number is then incremented to move to the next page.

The pagination values are passed in the URL’s query string. In general the following variables can be used:

Variable Description
page (int) The number of the page e.g. 1
perPage (int) The number of results per page e.g. 10
sortBy (string) The field to sort by e.g. createdTime
sortDirection (string) The direction to sort by e.g. desc

There are different ways you can check to see if another request needs to be made:

1) You can count the number of results. If you requested, say, 10 items per page and only 5 have been returned clearly there won’t be another page of results following that one.

2) You can check whether the ‘nextPage’ key is a URL. Each API response that returns multiple results includes a ‘prevPage’ and ‘nextPage’ key. These can either be null or a URL to that page of results.

The exception to both cases is when the number of results happens to match the number requested per page. For example if you ask for 10 items per page, and 10 are returned, there is not enough information to know whether there is an 11th item and so whether there is another page of results. Therefore the ‘nextPage’ attribute will be set in case. Upon requesting the next page, it is at that point that you will know, since the result set will then be empty, and the ‘nextPage’ attribute will be null accordingly.

Updating (PUT requests)

If you ever need to update a value to make it null, please be aware that you will need to send its value as the empty string “” in your PUT request. This is because we define null as meaning not set. So to avoid any confusion - setting a value as not set - sending “” will be recognised as meaning “not set”.

Rate-limiting

We currently impose a limit on the number of requests that can be made to the API over a period of time. Further requests will be denied and will return with a HTTP status code of 429.

The limit varies per endpoint.

As long as you follow best practices when making API requests, such as caching the responses where possible, this should not cause any problems for your application.

If you find you are hitting these limits, and caching (see above) does not solve the issue, please get in touch.

Updates

We are constantly improving the platform. API changes are a key part of this.

For example we may return extra data in a response, such as an additional key:value pair, or change the order elements appear.

We will try to notify you of any changes so that you can decide what action, if any, to take.

Activity

If activity logging is enabled for your account, you can retrieve data about changes to your account’s resources (creation, deletion and updates) by making the following requests:

Request Description
GET /activity Returns activity
POST /activity/search Searches the activity

GET /activity

Example request

curl -H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/activity?page=0&perPage=100&sortBy=requestTime&sortDirection=desc

Example response

{
    "activity": [
        {
            "accountId": "abcd",
            "requestTime": "2018-01-23T00:01:23+00:00",
            "requestType": "POST",
            "requestMadeFromIp": "1.2.3.4",
            "requestBy": {
                "id": "abcdefg",
                "name": "Test User",
                "email": "test.user@company.com"
            },
            "resourceId": "abcdefg",
            "resourceType": "playlist"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "requestTime",
    "sortDirection": "desc"
}

Returns the details of all activity in your account, subject to any pagination passed within its parameters.

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “requestTime”
sortDirection String “desc” Can be “asc” or “desc”

Response format

Each element in the returned activity array contains the following keys:

Key Type Description
accountId String A reference identifier for the account the resource belongs to
requestTime String The date and time of the action
requestType String The type of action
POST (resource created)
PUT (resource updated)
DELETE (resource deleted)
[Deprecated] requestMadeByUserId String The id of the user who made the request
[Deprecated] requestMadeByUserName String The name of the user who made the request
requestMadeFromIp String The IP address where the request came from
requestBy Object The ID, name and email of the user who made the request
resourceId String The id of the resource that was created, updated or deleted
resourceType String The type of resource that was created, updated or deleted

POST /activity/search

Example request

Here we are asking the API to return all actions that modified our resources performed since 1st January 2018. So we need an array containing one object. It should have the key requestTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl -g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"requestTime","comparison":"gte","value":"2018-01-01"}]'
https://vidbeo.com/api/v1/activity/search

Example response

{
    "activity": [
        {
            "accountId": "abcd",
            "requestTime": "2018-01-23T00:01:23+00:00",
            "requestType": "POST",
            "requestMadeFromIp": "1.2.3.4",
            "requestBy": {
                "id": "abcdefg",
                "name": "Test User",
                "email": "test.user@company.com"
            },
            "resourceId": "abcdefg",
            "resourceType": "playlist"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "requestTime",
    "sortDirection": "desc"
}

Searches the activity

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those actions which match them all.

Key Type Description
key String The field to search. Accepted values:
requestMadeByUserId
requestTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /activity request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Analytics

Retrieve analytics data for your videos by making the following request:

Request Description
GET /analytics Returns a report based on the options passed in the query string

It is a little more complicated. The example requests below should hopefully make it clear how it all works, but, as usual, if you have any questions please get in touch.

GET /analytics

The following example requests should hopefully make it clear how to use this endpoint. The starting point is always the question: what data you want to receive?

Q: How many views have all my videos had each day between 21st February 2018 and 25th February 2018?

Since the request is “each day” your interval value would be daily. That would be the optional parameter. So combined with the required result, start, end, and URL-encoded filters, your request would be (again, without the new-lines we added to make it more readable):

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/analytics?
result=count
&start=2018-02-21
&end=2018-02-25
&filters=%5B%7B%22property_name%22%3A%22event%22%2C%22operator%22%3A%22eq%22%2C%22property_value%22%3A%22played%22%7D%5D
&interval=daily

Example response

{
    "analytics": {
        "result": [
            {
                "value": 17,
                "timeframe": {
                    "start": "2018-02-21T00:00:00.000Z",
                    "end": "2018-02-22T00:00:00.000Z"
                }
            },
            {
                "value": 15,
                "timeframe": {
                    "start": "2018-02-22T00:00:00.000Z",
                    "end": "2018-02-23T00:00:00.000Z"
                }
            },
            {
                "value": 16,
                "timeframe": {
                    "start": "2018-02-23T00:00:00.000Z",
                    "end": "2018-02-24T00:00:00.000Z"
                }
            },
            {
                "value": 2,
                "timeframe": {
                    "start": "2018-02-24T00:00:00.000Z",
                    "end": "2018-02-25T00:00:00.000Z"
                }
            },
            {
                "value": 1,
                "timeframe": {
                    "start": "2018-02-25T00:00:00.000Z",
                    "end": "2018-02-25T23:59:59.999Z"
                }
            }
        ]
    }
}

As you can see, the interval was daily and so rather than a single value being returned, the result value is an array of objects. Each object is one day’s data. And that object contains the value - the number of views (played events), along with the corresponding day, the timeframe. So in this example the range was from the 21st February to the 25th February, as you can see in the response.

Q: How many views have all my videos had between 21st February 2018 and 25th February 2018, by device type?

Here, we are not splitting by an interval. We instead use our “by” parameter to split by device_type. That is one of the values we store during playback to work out the device type. That is obtained by parsing the browser’s user agent string (so it may be unreliable). So for this report, we use “by” as our optional parameter. Combined with the required result, start, end, and URL-encoded filters to only return a count of played events (see above), your request would be:

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/analytics?
result=count
&start=2018-02-21
&end=2018-02-25
&filters=%5B%7B%22property_name%22%3A%22event%22%2C%22operator%22%3A%22eq%22%2C%22property_value%22%3A%22played%22%7D%5D
&by=device_type

Example response

{
    "analytics": {
        "result": [
            {
                "result": 46,
                "device_type": "desktop"
            },
            {
                "result": 4,
                "device_type": "mobile"
            },
            {
                "result": 1,
                "device_type": "tablet"
            }
        ]
    }
}

As you can see, the response this time is an array, where each element is an object with a ‘result’ and ‘device_type’ attribute. The value of ‘result’ is the number of views from that device type within that date range.

For now the only type of result supported is count.

result=count

Each report will therefore return a count of the number of views that match the criteria specified in the rest of the query.

The next two parameters are for the start and end dates. These are also required and must be passed in the standard YYYY-MM-DD format. All times are UTC.

For example:

start=2018-02-21&end=2018-02-25

Next you will need to filter the events the report returns a count of. Since our system records different events during each playback, in order to get the number of views, you need to limit the report to only count events which equal (eq) played. That event is sent, yes, when the video is played.

Note: since there are a variety of properties, a variety of tests, and a variety of possible values, the filters to apply need to be passed as an array. Each element in that array is an object - which is one filter to apply.

So you will be sending this as JSON:

[{"property_name":"event", "operator":"eq", "property_value":"played"}]

… but that can’t be sent like that in a URL. It needs to be URL-encoded to make it safe. Every language will have some form of URL encode or URL decode function. But there is no need since we have done it for you here: this is the URL-encoded form of that JSON above, prefixed with filters= ready to be used in our query. If you peer at it closely, you can see what has been done, as the various characters have been converted into URL-safe equivalents:

filters=%5B%7B%22property_name%22%3A%22event%22%2C%22operator%22%3A%22eq%22%2C%22property_value%22%3A%22played%22%7D%5D

The good news is since you will likely need to send that value of ‘filters’ for every one of your queries, you can just copy-and-paste it. You just send that same value each time, in all your queries.

So combining all of the above, at this point your URL will look like this (we’ve added new-lines and spaces to make it more readable, but your URL should not have any):

https://vidbeo.com/api/v1/analytics? result=count &start=2018-02-21 &end=2018-02-25 &filters=%5B%7B%22property_name%22%3A%22event%22%2C%22operator%22%3A%22eq%22%2C%22property_value%22%3A%22played%22%7D%5D

To limit the number of results returned, you may want to add a limit value. Pagination is not supported, so this is primarily used if you are only interested in seeing the top X (such as 10) results, in which case you would use: limit=10

So now in order to make an actual report, you will use one of the parameters below: either using ‘interval’ to group by a time-range, or using ‘by’ to group by a particular attribute. You can think of the value of the interval, or the value of the attribute, as being like the x-axis on a graph. The returned value/result (the number of views) would therefore be plotted on the y-axis. So you could use:

1) interval

We currently support hourly, daily and weekly for the value of interval. For example: interval=daily.

… OR …

2) by

The other way to group the returned values is with “by”. This needs to be the name of one of our supported metrics - you can contact us if interested in using this. Common ones are title and page_url. As the name suggests, and as you can see in the examples in the other column, the report is then returned grouped by the values of that metric.

Response format

Key Type Description
analytics Object The generated report, returned in the ‘result’ key

Captions

You can manipulate closed captions (CC) within your account by making the following requests:

Request Description
GET /captions/:id Returns the details of a single set of captions
GET /captions Returns the details of all of the captions in your account, subject to any filtering or pagination passed within its parameters
PUT /captions/:id Updates a set of caption’s attributes
DELETE /captions/:id Deletes a set of captions
POST /captions Creates a new set of captions

GET /captions/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/captions/abcdefg

Example response

{
    "id": "abcdefgh",
    "accountId": "abcd",
    "title": "Example captions",
    "description": "",
    "code": "en",
    "language": "English",
    "content": [
        {
            "start": 1,
            "end": 2,
            "text": "This is a caption"
        },
        ...
    ],
    "createdBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "createdTime": "2018-01-235T00:12:34+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:12:34+00:00"
}

Returns the details of a single set of captions

Response format

Key Type Description
id String The unique identifier given to these captions
accountId String A reference identifier for the account they belong to
title String A reference title given to this caption e.g. English
description String Its description
code String The caption language’s code (ISO-639-1 format)
language String The full name of the language the captions are in
content Array Each element is an object with three keys:
start (the time in seconds the text should appear)
end (the time in seconds that text should disappear)
text (its text)
[Deprecated] createdByUserId String The id of the user who created this caption
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time this was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the caption
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the caption was last modified

GET /captions

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/captions?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "captions": [
        {
            "id": "abcdefgh",
            "accountId": "abcd",
            "title": "Example captions",
            "description": "",
            "code": "en",
            "language": "English",
            "content": [
                {
                    "start": 1,
                    "end": 2,
                    "text": "This is a caption"
                },
                ...
            ],
            "createdBy": {
                "id": "abcdefg",
                "name": "Test User",
                "email": "test.user@company.com"
            },
            "createdTime": "2018-01-235T00:12:34+0100",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Test User",
                "email": "test.user@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:12:34+0100"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the sets of captions in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime”
sortDirection String “desc” Can be “asc” or “desc”

PUT /captions/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT -d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/captions/abcdefg

Example response

{
    "id": "abcdefgh",
    "accountId": "abcd",
    "title": "New title",
    "description": "New description",
    "code": "en",
    "language": "English",
    "content": [
        {
            "start": 1,
            "end": 2,
            "text": "This is a caption"
        },
        ...
    ],
    "createdBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "createdTime": "2018-01-235T00:12:34+0100",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:12:34+0100"
}

Updates the attributes of some captions

The body of the request should contain one, or more, attributes that you would like to update for the caption

Important: Please be very careful when updating. If you update the value for a top-level key, its entire value will be replaced with the data you supply

DELETE /captions/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/captions/abcdefg

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a caption

POST /captions

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title","code":"en","language":"English"}'
https://vidbeo.com/api/v1/captions

Example response

{
    "id": "abcdefgh",
    "accountId": "abcd",
    "title": "New captions",
    "description": null,
    "code": "en",
    "language": "English",
    "content": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "createdTime": "2018-01-23T00:12:34+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Test User",
        "email": "test.user@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:12:34+0000"
}

Creates a new set of captions for a video

Required parameters

The required parameters are the title to give to these captions, the code of the language they are in (ISO-639-1 format) and the name of the language they are in. All other attributes will be set to default values that you can later edit.

Key Type Description
title String The title the caption is given (1-100 characters)
code String The ISO-639-1 code of the language (e.g. “en”)
language String The name of the language (e.g. “English”)

Optional parameters

Key Type Description
description String The description to give to these captions
content Array The content of these captions. If provided, each element must be an object with three keys:
start (the time in seconds it should appear)
end (the time in seconds it should disappear)
text (its text)

Categories

Categories can be used to label videos within your content library.

You can manipulate your categories by making the following requests:

Request Description
GET /categories/:id Returns the details of a single category
GET /categories Returns the details of all of the categories in your account, subject to any filtering or pagination passed within its parameters
PUT /categories/:id Updates a category’s attributes
DELETE /categories/:id Deletes a category
POST /categories Creates a new category
POST /categories/search Searches your categories

GET /categories/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/categories/abcdefgh

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "name": "Cars",
    "value": "cars",
    "createdBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "createdTime": "2018-06-30T00:00:01+00:00",
    "lastModifiedBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "lastModifiedTime": "2018-06-30T00:00:01+00:00"
}

Returns the details of a category

Response format

Key Type Description
id String The unique identifier given to this category
accountId String A reference identifier for the account the category belongs to
name String The name of this category (its label)
value String The value of this category
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the category was created
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the category was last modified

GET /categories

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/categories?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "categories": [
        {
            "id": "abcdefgh",
            "accountId": "abcde",
            "name": "Cars",
            "value": "cars",
            "createdBy": {
                "id": "abcdefgh",
                "name": "Example User",
                "email": "example.user@company.com"
            },
            "createdTime": "2018-06-30T00:00:01+00:00",
            "lastModifiedBy": {
                "id": "abcdefgh",
                "name": "Example User",
                "email": "example.user@company.com"
            },
            "lastModifiedTime": "2018-06-30T00:00:01+00:00"
        }
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage": null,
    "nextPage": null
}

Returns the details of all of the categories in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:“createdTime”“name”
sortDirection String “desc” Accepted values:“asc”“desc”

PUT /categories/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"name":"Test", "value":"test"}'
https://vidbeo.com/api/v1/categories/abcdefgh

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "name": "Test",
    "value": "test",
    "createdBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "createdTime": "2018-06-30T00:00:01+00:00",
    "lastModifiedBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "lastModifiedTime": "2018-06-30T00:00:02+00:00"
}

Updates the attributes of a category

The body of the request should contain one, or more, attributes that you would like to update for the category. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys

DELETE /categories/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/categories/abcdefgh

Example successful response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a category

POST /categories

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"name":"Cars","value":"cars"}'
https://vidbeo.com/api/v1/categories

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "name": "Cars",
    "value": "cars",
    "createdBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "createdTime": "2018-06-30T00:00:01+00:00",
    "lastModifiedBy": {
        "id": "abcdefgh",
        "name": "Example User",
        "email": "example.user@company.com"
    },
    "lastModifiedTime": "2018-06-30T00:00:01+00:00"
}

Creates a new category

Required parameters

Its name and its corresponding value. These can be the same, but normally they are used in the context of populating a dropdown menu. For example the name might be ‘Cars’ (the label, as a formatted string), and the value a lowercase version, held internally, ‘cars’.

Key Type Description
name String The name of the category (1-40 characters)
value String The value of the category (1-40 characters)

POST /categories/search

Example request

Here we are asking the API to return all categories created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/categories/search

Example response

{
    "categories": [
        {
            "id": "abcdefgh",
            "accountId": "abcde",
            "name": "Cars",
            "value": "cars",
            "createdBy": {
                "id": "abcdefgh",
                "name": "Example User",
                "email": "example.user@company.com"
            },
            "createdTime": "2018-06-30T00:00:01+00:00",
            "lastModifiedBy": {
                "id": "abcdefgh",
                "name": "Example User",
                "email": "example.user@company.com"
            },
            "lastModifiedTime": "2018-06-30T00:00:01+00:00"
        }
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage": null,
    "nextPage": null
}

Searches the categories

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those categories which match them all.

Key Type Description
key String The field to search. Accepted values:
namecreatedTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /categories request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

DRM

If DRM has been enabled for your account, you can request a new DRM token (licence URL) by making the following requests:

Request Description
GET /drm/tokens/:id Returns a new token

GET /drm/tokens/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/drm/tokens/vabcdefgh?expiresIn=3600

Example response

{
    "tokens": {
        "widevine": {
            "url": "https://vidbeo.com/Widevine/?KID=8fe9-abcde-1234-9a71&token=eyJ0eXAiOiJKV1Qi",
            "expires": "2018-05-05T12:00:00+00:00"
        },
        "playready": {
            "url": "https://vidbeo.com/PlayReady/?token=eyJ0LPAiOiJKV1QiLC",
            "expires": "2018-05-05T12:00:00+00:00"
        }
    }
}

Request a new DRM token.

The URL must contain the ID of the video asset to return the token(s) for.

An optional parameter can be passed in the query string: expiresIn. This is an integer that specifies the number of seconds the token will be valid for. If not specified, your account’s default value will be used. If that is not specified either, we default to 3600 seconds (an hour from the request).

Required parameters

Name Type Default Information
id String null The ID of the video asset, for example vabcdefgh

Optional parameters

Name Type Default Information
expiresIn Int 3600 The number of seconds the token(s) should be valid for

Response format

The returned object contains the following keys:

Key Type Description
tokens Object Contains one or more of widevine, playready and fairplay.

Groups

Groups can be used to organise items within your content library.

Note: groups act like labels rather than folders. They are virtual containers. This means that an item (such as a video) can be “in” more than one group. It also means that a group does not report its “contents”. Instead that relationship is maintained at the item-level. An item will maintain an array of the IDs of the groups it is “in” (if any) within its inGroups key.

You can manipulate your groups by making the following requests:

Request Description
GET /groups/:id Returns the details of a single group
GET /groups Returns the details of all of the groups in your account, subject to any filtering or pagination passed within its parameters
PUT /groups/:id Updates a group’s attributes
DELETE /groups/:id Deletes a group
POST /groups Creates a new group
POST /groups/search Searches your groups

GET /groups/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/groups/abcdefgh

Example response

{
  "id": "abcdefgh",
  "accountId": "abcde",
  "title": "Example group",
  "description": null,
  "parentGroupId": null,
  "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "createdTime": "2018-01-01T12:00:00+00:00",
  "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "lastModifiedTime": "2018-01-01T12:00:00+00:00"
}

Returns the details of a single group

Response format

Key Type Description
id String The unique identifier given to this group
accountId String A reference identifier for the account the group belongs to
title String The title given to this group
description String The description given to this group
parentGroupId String If this group has a parent, this holds the ID of that group
[Deprecated] createdByUserId String The id of the user who created the group
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the group was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the group
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the group was last modified

GET /groups

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/groups?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
  "groups": [
    {
      "id": "abcdefgh",
      "accountId": "abcde",
      "title": "Example group",
      "description": null,
      "parentGroupId": null,
      "createdByUserId": "abcde1234",
      "createdTime": "2018-01-01T12:00:00+00:00",
      "lastModifiedByUserId": "abcde1234",
      "lastModifiedTime": "2018-01-01T12:00:00+00:00"
    },
    ...
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc",
  "prevPage": null,
  "nextPage": null
}

Returns the details of all of the groups in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /groups/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/groups/abcdefgh

Example response

{
  "id": "abcdefgh",
  "accountId": "abcde",
  "title": "New title",
  "description": "New description",
  "parentGroupId": null,
  "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "createdTime": "2018-01-01T12:00:00+00:00",
  "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "lastModifiedTime": "2018-01-01T12:00:00+00:00"
}

Updates the attributes of a group

The body of the request should contain one, or more, attributes that you would like to update for the group. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys

DELETE /groups/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/groups/abcdefgh

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a group

POST /groups

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title"}'
https://vidbeo.com/api/v1/groups

Example response

{
  "id": "abcdefgh",
  "accountId": "abcde",
  "title": "New title",
  "description": null,
  "parentGroupId": null,
  "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "createdTime": "2018-01-01T12:00:00+00:00",
  "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
  },
  "lastModifiedTime": "2018-01-01T12:00:00+00:00"
}

Creates a new group

Required parameters

The only required parameter is the title of the group.

Key Type Description
title String The title of the group (1-100 characters)

Optional parameters

Key Type Description
description String The description to give to this group
parentGroupId String If you would like this group to be visually shown within another, you can provide the ID of that parent group

POST /groups/search

Example request

Here we are asking the API to return all groups created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/groups/search

Example response

{
  "groups": [
    {
      "id": "abcdefgh",
      "accountId": "abcde",
      "title": "Example group",
      "description": null,
      "parentGroupId": null,
      "createdBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "createdTime": "2018-01-01T12:00:00+00:00",
      "lastModifiedBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "lastModifiedTime": "2018-01-01T12:00:00+00:00"
    },
    ...
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc",
  "prevPage": null,
  "nextPage": null
}

Searches the groups

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those groups which match them all.

Key Type Description
key String The field to search. Accepted values:
title
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /groups request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Images

These are the images used for logos and video poster frames.

You can manipulate your images by making the following requests:

Request Description
GET /images/:id Returns the details of a single image
GET /images Returns the details of all of the images in your account, subject to any filtering or pagination passed within its parameters
PUT /images/:id Updates an image’s attributes
DELETE /images/:id Deletes an image
POST /images Creates a new image
POST /images/search Searches your images

GET /images/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/images/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "Example image",
    "description": null,
    "type": "logo",
    "filePrefix": "abcdefg",
    "sourceFile": {
        "name": "example.png"
    },
    "imageFiles": [
        {
            "type": "logo",
            "width": 100,
            "height": 25,
            "name": "xyz.png",
            "url": "https//...",
            "fileSize": 123,
            "imageCodec": "png",
            "label": "23p"
        },
        ...
    ],
    "progress": "completed",
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Returns the details of an image.

Response format

Key Type Description
id String The unique identifier given to this image
accountId String A reference identifier for the account the image belongs to
title String The title given to this image
description String The description given to this image
type String The image’s type can either be “logo” or “poster”
filePrefix String A unique prefix for the files generated for this image
sourceFile Object Details of the image file that was originally uploaded
imageFiles Array The available images that can be used to represent the image
progress String The image’s verification progress. This can be either “waiting”, “processing”, “completed” or “failed”
inGroups Array Each element is a group’s id
tags Array Each element is a tag
[Deprecated] createdByUserId String The id of the user who uploaded the image
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the image was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the image
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the image was last modified

GET /images

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/images?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "images": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example image",
            "description": null,
            "type": "logo",
            "filePrefix": "abcdefg",
            "sourceFile": {
                "name": "xyz.png"
            },
            "imageFiles": [
                {
                    "type": "logo",
                    "width": 100,
                    "height": 25,
                    "name": "xyz.png",
                    "url": "//...",
                    "fileSize": 123,
                    "imageCodec": "png",
                    "label": "23p"
                },
                ...
            ],
            "progress": "completed",
            "tags": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0000",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the images in your account, subject to any filtering or pagination passed within its parameters.

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /images/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/images/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": "New description",
    "type": "logo",
    "filePrefix": "abcdefg",
    "sourceFile": {
        "name": "example.png"
    },
    "imageFiles": [
        {
            "type": "logo",
            "width": 100,
            "height": 25,
            "name": "xyz.png",
            "url": "https://...",
            "fileSize": 123,
            "imageCodec": "png",
            "label": "23p"
        },
        ...
    ],
    "progress": "completed",
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+00:00"
}

Updates the attributes of an image.

The body of the request should contain one, or more, attributes that you would like to update for the image. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.

DELETE /images/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/images/abcdefg

Example response.

No data will be returned, as the resource has been deleted.

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes an image.

POST /images

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title","type":"poster","sourceFile":{"name":"xyz.jpg","url":"http://abc.com/xyz.jpg"}}'
https://vidbeo.com/api/v1/images

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": null,
    "type": "poster",
    "filePrefix": "abcdefg",
    "sourceFile": {
        "name": "xyz.jpg"
    },
    "imageFiles": null,
    "progress": "waiting",
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+00:00"
}

Creates a new image.

Required parameters

The required parameters are the title the image should be given, the type of the image, and the details of its source file.

The source file needs to have two attributes: a name, and a full URL from where our system can access it. All other attributes will be set to default values that you can later edit.

Key Type Description
title String The title the image is given (1-100 characters)
type String The type of image. Accepted values:
logo
poster
sourceFile Object The image file. It must contain two keys:
name e.g. xyz.png
url e.g. http://abc.com/xyz.png

Note: There are restrictions on the image, based on its type. If it is a logo, then the image must be a .png file, under 20KB and be a maximum of 300px x 300px. If it is a poster frame, then the image must be a .jpg file, under 100KB

Optional parameters

Key Type Description
description String The description to give to this image

POST /images/search

Example request

Here we are asking the API to return all images created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/images/search

Example response

{
    "images": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example image",
            "description": null,
            "type": "logo",
            "filePrefix": "abcdefg",
            "sourceFile": {
                "name": "xyz.png"
            },
            "imageFiles": [
                {
                    "type": "logo",
                    "width": 100,
                    "height": 25,
                    "name": "xyz.png",
                    "url": "https://...",
                    "fileSize": 123,
                    "imageCodec": "png",
                    "label": "23p"
                },
                ...
            ],
            "progress": "completed",
            "tags": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2014-01-23T00:01:23+00:00",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2014-01-23T00:01:23+00:00"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc"
}

Searches the images

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those images which match them all.

Key Type Description
key String The field to search. Accepted values:
title
progress
type
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /images request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Players

An embedded item, such as a video, playlist or live stream, is shown within a player. So to make it easier to change the settings for many in one go, we group those settings into a player object. For example you may want to change which controls are shown. Apply that once, and all videos shown in that player automatically update.

You can manipulate players within your account by making the following requests:

Request Description
GET /players/:id Returns the details of a single player
GET /players Returns the details of all of the players in your account, subject to any filtering or pagination passed within its parameters
PUT /players/:id Updates a player’s attributes
DELETE /players/:id Deletes a player
POST /players Creates a new player
POST /players/search Searches the players

GET /players/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/players/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "Example player",
    "description": null,
    "width": "640px",
    "height": "360px",
    "settings": {
        "preload": false,
        "aspectRatio": 0.5625,
        "api": {
            "enabled": true,
            "domain": null
        },
        "ui": {
            "enabled": true,
            "display": "auto",
            "device": "auto",
            "onlyPlayButton": false,
            "showTitle": false,
            "nativeControlsTouch": true
        },
        "logo": {
            "enabled": false,
            "link": "http://img.jpg",
            "url": "http://page.com"
        },
        "sharing": {
            "enabled": false
        },
        "captions": {
            "defaultOn": false
        },
        "analytics": {
            "google": {
                "enabled": true,
                "domain": "xyz.com",
                "id": "UA-12345678-1",
                "demographics": true
            }
        },
        "advertising": {
            "enabled": false,
            "type": null,
            "tag": null
        },
        "buffering": {
            "goal": 20
        }
    },
    "styles": null,
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0100",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0100"
}

Returns the details of a player

Response format

Key Type Description
id String The unique identifier given to this player
accountId String A reference identifier for the account the player belongs to
title String The title given to this player
description String The description given to this player
width String The width a video or playlist using this player should be embedded at
height String The height a video or playlist using this player should be embedded at
settings Object How the player should work
styles String Overrides to how the player should look
inGroups Array Each element is a group’s id
tags Array Each element is a tag
[Deprecated] createdByUserId String The id of the user who created the player
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the player was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the player
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the player was last modified

GET /players

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/players?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "players": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example player",
            "description": null,
            "width": "640px",
            "height": "360px",
            "settings": {
                "preload": false,
                "aspectRatio": 0.5625,
                "api": {
                    "enabled": true,
                    "domain": null
                },
                "ui": {
                    "enabled": true,
                    "display": "auto",
                    "device": "auto",
                    "onlyPlayButton": false,
                    "showTitle": false,
                    "nativeControlsTouch": true
                },
                "logo": {
                    "enabled": false,
                    "link": "",
                    "url": ""
                },
                "sharing": {
                    "enabled": false
                },
                "captions": {
                    "defaultOn": false
                },
                "analytics": {
                    "google": {
                        "enabled": true,
                        "domain": "xyz.com",
                        "id": "UA-12345678-1",
                        "demographics": true
                    }
                },
                "advertising": {
                    "enabled": false,
                    "type": null,
                    "tag": null
                },
                "buffering": {
                    "goal": 20
                }
            },
            "styles": null,
            "tags": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0100",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        }
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the players in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /players/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/players/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": "New description",
    "width": "640px",
    "height": "360px",
    "settings": {
        "preload": false,
        "aspectRatio": 0.5625,
        "api": {
            "enabled": true,
            "domain": null
        },
        "ui": {
            "enabled": true,
            "display": "auto",
            "device": "auto",
            "onlyPlayButton": false,
            "showTitle": false,
            "nativeControlsTouch": true
        },
        "logo": {
            "enabled": false,
            "link": "http://img.jpg",
            "url": "http://page.com"
        },
        "sharing": {
            "enabled": false
        },
        "captions": {
            "defaultOn": false
        },
        "analytics": {
            "google": {
                "enabled": true,
                "domain": "xyz.com",
                "id": "UA-12345678-1",
                "demographics": true
            }
        },
        "advertising": {
            "enabled": false,
            "type": null,
            "tag": null
        },
        "buffering": {
            "goal": 20
        }
    },
    "styles": null,
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0100",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0100"
}

Updates the attributes of a player.

The body of the request should contain one, or more, attributes that you would like to update for the player.

Important: Please be very careful when updating a player. Keep in mind that when replacing a value for a top-level key, such as styles, the entire value will be replaced with the data you supply for it. If you intend to just change one colour you still need to send the entire value.

DELETE /players/:id

Example request:

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/players/abcdefg

Example response

No data will be returned, as the resource has been deleted.

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a player.

POST /players

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title","settings":{see above},"styles":{see above}}'
https://vidbeo.com/api/v1/players

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": null,
    "width": "640px",
    "height": "360px",
    "settings": {
        "preload": false,
        "aspectRatio": 0.5625,
        "api": {
            "enabled": true,
            "domain": null
        },
        "ui": {
            "enabled": true,
            "display": "auto",
            "device": "auto",
            "onlyPlayButton": false,
            "showTitle": false,
            "nativeControlsTouch": true
        },
        "logo": {
            "enabled": false,
            "link": "http://img.jpg",
            "url": "http://page.com"
        },
        "sharing": {
            "enabled": false
        },
        "commenting": {
            "enabled": true
        },
        "captions": {
            "defaultOn": false
        },
        "analytics": {
            "google": {
                "enabled": true,
                "domain": "xyz.com",
                "id": "UA-12345678-1",
                "demographics": true
            }
        },
        "advertising": {
            "enabled": false,
            "type": null,
            "tag": null
        },
        "buffering": {
            "goal": 20
        }
    },
    "styles": null,
    "tags": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0100",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0100"
}

Creates a new player

Required parameters

The only required parameters are the title the player should be given, its settings, and its styles. Since our embed code will look for specific key:value pairs within the player’s data, please make sure you maintain exactly the same structure as we use for our players

Key Type Description
title String The title the video is given (1-100 characters)
settings Object How the player should work

Optional parameters

Key Type Description
description String The description to give to this player
width String The width a video or playlist using this player should be embedded atIf no value is specified, it will default to 640px
height String The height a video or playlist using this player should be embedded atIf no value is specified, it will default to 360px

POST /players/search

Example request

Here we are asking the API to return all players created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/players/search

Example response

{
    "players": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example player",
            "description": null,
            "width": "640px",
            "height": "360px",
            "settings": {
                "preload": false,
                "aspectRatio": 0.5625,
                "api": {
                    "enabled": true,
                    "domain": null
                },
                "ui": {
                    "enabled": true,
                    "display": "auto",
                    "device": "auto",
                    "onlyPlayButton": false,
                    "showTitle": false,
                    "nativeControlsTouch": true
                },
                "logo": {
                    "enabled": false,
                    "link": "",
                    "url": ""
                },
                "sharing": {
                    "enabled": false
                },
                "captions": {
                    "defaultOn": false
                },
                "analytics": {
                    "google": {
                        "enabled": true,
                        "domain": "xyz.com",
                        "id": "UA-12345678-1",
                        "demographics": true
                    }
                },
                "advertising": {
                    "enabled": false,
                    "type": null,
                    "tag": null
                },
                "buffering": {
                    "goal": 20
                }
            },
            "styles": null,
            "tags": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0100",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        }
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc"
}

Searches the players

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those players which match them all.

Key Type Description
key String The field to search. Accepted values:
title
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /players request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Playlists

A playlist is a sequence of videos, played one after another.

You can manipulate playlists by making the following requests:

Request Description
GET /playlists/:id Returns the details of a single playlist
GET /playlists Returns the details of all of the playlists in your account, subject to any filtering or pagination passed within its parameters
PUT /playlists/:id Updates a playlist’s attributes
DELETE /playlists/:id Deletes a playlist
POST /playlists Creates a new playlist
POST /playlists/search Searches the playlists
POST /playlists/search/total Searches the playlists

GET /playlists/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/playlists/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "Example playlist",
    "description": null,
    "type": "manual",
    "filter": null,
    "videos": [
        "abcdefg",
        ...
    ],
    "playerId": "abcdefg",
    "restrictionId": null,
    "shareUrl": "https://...",
    "enabled": true,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Note: The keys returned in the response will vary depending upon whether it is enabled, since if not, that means its data should not be made available

For example you may receive only a subset of the data.

Returns the details of a playlist

Response format

Key Type Description
id String The unique identifier given to this playlist
accountId String A reference identifier for the account the playlist belongs to
title String The title given to this playlist
description String The description given to this playlist
type String The playlist’s type (only “manual” supported)
filter Object No longer applicable: how the system should select its videos
videos Array Each element is a string, which is the id of a video
playerId String The id of the player the playlist should be shown in
restrictionId String A playlist will be public by default. However access can be restricted by IP and/or country by applying a restriction to it
shareUrl String The URL a viewer will be prompted to share if they opt to do so
enabled Boolean A playlist can be temporarily disabled to block access to it rather than deleting it
inGroups Array Each element is a group’s id
tags Array Each element is a tag
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field returns your own key,value pairs
[Deprecated] createdByUserId String The id of the user who created the playlist
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the playlist was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the playlist
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the playlist was last modified

GET /playlists

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/playlists?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "playlists": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example playlist",
            "description": null,
            "type": "manual",
            "filter": null,
            "videos": [
                "abcdefg",
                ...
            ],
            "playerId": "abcdefg",
            "restrictionId": null,
            "shareUrl": "https://...",
            "enabled": true,
            "tags": null,
            "metadata": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0000",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the playlists in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /playlists/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/playlists/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": "New description",
    "type": "manual",
    "filter": null,
    "videos": [
        "abcdefg",
        ...
    ],
    "playerId": "abcdefg",
    "restrictionId": null,
    "shareUrl": "https://...",
    "enabled": true,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Updates the attributes of a playlist

The body of the request should contain one, or more, attributes that you would like to update for the playlist

Important: Please be very careful when updating a playlist. Keep in mind that when replacing a value for a top-level key, the entire value will be replaced with the data you supply for it. If you intend to just change one part of it, you still need to send the entire value

DELETE /playlists/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/playlists/abcdefg

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a playlist

POST /playlists

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title"}'
https://vidbeo.com/api/v1/playlists

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": null,
    "type": "manual",
    "filter": null,
    "videos": null,
    "playerId": "abcdefg",
    "restrictionId": null,
    "shareUrl": "https://...",
    "enabled": true,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Creates a new playlist

Required parameters

The only required parameter is the title the playlist should be given. This will create an empty, manually-populated playlist, and default values will be provided for attributes such as the player it is presented in.

Key Type Description
title String The title the playlist is given (1-100 characters)

Optional parameters

Key Type Description
description String The description to give to this playlist
type String Must be “manual”
filter Object This used to be provided to specify the maxLength and type of filter
videos Array Each element should be a string, which is the id of a video
playerId String The id of the player the playlist should be shown in
restrictionId String A playlist will be public by default. However access can be restricted by IP and/or country by applying a restriction to it
shareUrl String The URL a viewer will be prompted to share if they opt to do so
enabled Boolean A playlist can be temporarily disabled to block access to it rather than deleting it
tags Array Each element should be a single alphanumeric lowercase string
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field can contain your own key,value pairs

POST /playlists/search

Example request

Here we are asking the API to return all playlists created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/playlists/search

Example response

{
    "playlists": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example playlist",
            "description": null,
            "type": "manual",
            "filter": null,
            "videos": [
                "abcdefg",
                ...
            ],
            "playerId": "abcdefg",
            "restrictionId": null,
            "shareUrl": "https://...",
            "enabled": true,
            "tags": null,
            "metadata": null,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0000",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc"
}

Searches the playlists

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those playlists which match them all.

Key Type Description
key String The field to search. Accepted values:
title
enabled
videos
playerId
restrictionId
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /playlists request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

POST /playlists/search/total

Example request

Here we are asking the API to return the number of playlists created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/playlists/search/total

Example response

{
  "count": 123
}

Searches the playlists

The difference between this and the request above is - as the URL suggests - that this version only returns the number of matches. Accordingly, pagination and sorting variables should not be passed in the query string as they would not make sense.

Restrictions

By default all embedded items are public. That is because they are designed to be embedded on your site, or shared on social media, and therefore the viewer would not be logged in to our system.

However you may prefer to limit who can access your content. For example you could add the IP range of your corporate network and any request not originating from within that range would be denied.

This is done by creating a restriction, and then applying that restriction to your videos, playlists and streams.

You can manipulate restrictions by making the following requests:

Request Description
GET /restrictions/:id Returns the details of a single restriction
GET /restrictions Returns the details of all of the restrictions in your account, subject to any filtering or pagination passed within its parameters
PUT /restrictions/:id Updates a restriction’s attributes
DELETE /restrictions/:id Deletes a restriction
POST /restrictions Creates a new restriction
POST /restrictions/search Searches the restrictions

GET /restrictions/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/restrictions/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "Example restriction",
    "description": null,
    "user": null,
    "ip": [
        "1.2.3.4"
    ],
    "geo": [
        "GB"
    ],
    "domain": [
        "company.com"
    ],
    "sso": null,
    "password": false,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Returns the details of a restriction

Response format

Key Type Description
id String The unique identifier given to this restriction
accountId String A reference identifier for the account the restriction belongs to
title String The title given to this restriction
description String The description given to this restriction
user Array Restrict by user: each element is a string, which can either be the keyword “all”, or a particular user’s ID
ip Array Restrict by IP: each element is a string, which can be an IP address or range
geo Array Restrict by location: each element is a string, which is an ISO-3166-1 country code
domain Array Restrict by domain: each element is a string, which is a domain
sso Object Restrict using Single Sign-On: the details of your single sign-on provider
password Boolean Is a password required?
[Deprecated] createdByUserId String The id of the user who created the restriction
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the restriction was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the restriction
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the restriction was last modified

Please contact us if you have a specific set of countries/IPs but are not sure how to define them.

GET /restrictions

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/restrictions?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "restrictions": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example restriction",
            "description": null,
            "user": null,
            "ip": [
                "1.2.3.4"
            ],
            "geo": [
                "GB"
            ],
            "domain": [
                "company.com"
            ],
            "sso": null,
            "password": false,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0000",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the restrictions in your account, subject to any pagination passed within its parameters.

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /restrictions/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/restrictions/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": "New description",
    "user": null,
    "ip": [
        "1.2.3.4"
    ],
    "geo": [
        "GB"
    ],
    "domain": null,
    "sso": null,
    "password": false,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Updates the attributes of a restriction

The body of the request should contain one, or more, attributes that you would like to update for the restriction

Important: Please be very careful when updating a restriction. Keep in mind that when replacing a value for a top-level key, the entire value will be replaced with the data you supply for it

DELETE /restrictions/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/restrictions/abcdefg

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a restriction

POST /restrictions

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title","geo":["GB"]}'
https://vidbeo.com/api/v1/restrictions

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "title": "New title",
    "description": null,
    "user": null,
    "ip": null,
    "geo": [
        "GB"
    ],
    "domain": null,
    "sso": null,
    "password": false,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+0000",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+0000"
}

Creates a new restriction

Required parameters

The only required parameter is the title the restriction should be given. This wouldn’t be much use in production, since it would deny access to everybody.

Key Type Description
title String The title the restriction is given (1-100 characters)

Optional parameters

Key Type Description
description String The description to give to this restriction
ip Array An array of IP addresses
geo Array An array of ISO-3166-1 country codes
domain Array An array of domains
sso Object The details of your single sign-on provider

POST /restrictions/search

Example request

Here we are asking the API to return all restrictions created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/restrictions/search

Example response

{
    "restrictions": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "title": "Example restriction",
            "description": null,
            "user": null,
            "ip": [
                "1.2.3.4"
            ],
            "geo": [
                "GB"
            ],
            "domain": [
                "company.com"
            ],
            "sso": null,
            "password": false,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+0000",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+0000"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc"
}

Searches the restrictions

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those restrictions which match them all.

Key Type Description
key String The field to search. Accepted values:
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /restrictions request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Streams

Streams (short for live streams) are live broadcasts of events - as opposed to a recording of an event that has already happened (a video, known as VoD).

Note: Please contact us if you wish to enable live streaming for your account, as there are additional charges for ingest.

You can manipulate the streams within your account by making the following requests:

Request Description
GET /streams/:id Returns the details of a stream
GET /streams Returns the details of all of the streams in your account (subject to any pagination passed within its parameters)
PUT /streams/:id Updates a stream’s attributes
DELETE /streams/:id Deletes a stream
POST /streams Creates a new stream
POST /streams/search Searches the streams
POST /streams/search/total Searches the streams

GET /streams/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/streams/abcdefg

Example response

{
    "id": "sabcdefg",
    "accountId": "abcde",
    "title": "Example stream",
    "description": null,
    "startTime": "2017-05-01T00:00:00+00:00",
    "endTime": "2017-05-01T01:00:00+00:00",
    "ingestId": "abcde-12345",
    "ingestUrl": "rtmp://ingest-url",
    "ingestKey": "stream",
    "imageFiles": [
        {
            "type": "poster",
            "width": 852,
            "height": 480,
            "name": "abcdefj_480p.jpg",
            "url": "https://url.jpg",
            "fileSize": 1234,
            "imageCodec": "jpg",
            "label": "480p"
        }
    ],
    "videoFiles": [
        {
            "name": "index.m3u8",
            "url": "https://path/index.m3u8",
            "videoCodec": "h264",
            "audioCodec": "aac",
            "fileSize": 0,
            "label": "hls"
        }
    ],
    "playerId": "labcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/w/sabcdefg",
    "encoderId": "eabcdefgh",
    "enabled": true,
    "inGroups": null,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2015-05-10T10:00:00+0100",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2015-05-10T10:00:00+0100"
}

Returns the details of a stream

Response format

Key Type Description
id String The unique identifier given to this stream
accountId String A reference identifier for the account the stream belongs to
title String The title given to this stream
description String The description given to this stream
startTime String The date and time the stream starts
endTime String The date and time the stream ends
ingestId String The ID of the ingest point
ingestUrl String The URL of the ingest point
ingestKey String The key for the ingest point
imageFiles Array Image(s) used to represent the stream. There will normally be one.
videoFiles Array The generated version(s): each element is an object containing the details of one output
playerId String The id of the player the stream should be shown in
restrictionId String A stream will be public by default. However access can be restricted (such as by IP) by applying a restriction to it
shareUrl String The URL a viewer will be prompted to share if they opt to do so
enabled Boolean A stream can be temporarily disabled to block access to it rather than deleting it
inGroups Array Each element is a group’s id
tags Array Each element is a tag
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field returns your own key,value pairs
[Deprecated] createdByUserId String The id of the user who created the stream
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the stream was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the stream
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the stream was last modified

GET /streams

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/streams?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
  "streams": [
    {
        "id": "sabcdefg",
        "accountId": "abcde",
        "title": "Example stream",
        "description": null,
        "startTime": "2017-05-01T00:00:00+00:00",
        "endTime": "2017-05-01T01:00:00+00:00",
        "ingestId": "abcde-12345",
        "ingestUrl": "rtmp://ingest-url",
        "ingestKey": "stream",
        "imageFiles": [
            {
                "type": "poster",
                "width": 852,
                "height": 480,
                "name": "abcdefj_480p.jpg",
                "url": "https://url.jpg",
                "fileSize": 1234,
                "imageCodec": "jpg",
                "label": "480p"
            }
        ],
        "videoFiles": [
            {
                "name": "index.m3u8",
                "url": "https://path/index.m3u8",
                "videoCodec": "h264",
                "audioCodec": "aac",
                "fileSize": 0,
                "label": "hls"
            }
        ],
        "playerId": "labcdefgh",
        "restrictionId": null,
        "shareUrl": "https://vidbeo.com/w/sabcdefg",
        "encoderId": "eabcdefgh",
        "enabled": true,
        "inGroups": null,
        "tags": null,
        "metadata": null,
        "createdBy": {
            "id": "abcdefg",
            "name": "Example Person",
            "email": "example.person@company.com"
        },
        "createdTime": "2018-05-10T10:00:00+0100",
        "lastModifiedBy": {
            "id": "abcdefg",
            "name": "Example Person",
            "email": "example.person@company.com"
        },
        "lastModifiedTime": "2018-05-10T10:00:00+0100"
    },
    {
    ...
    }
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc",
  "prevPage":null,
  "nextPage":null
}

Returns the details of all of the streams in your account, subject to any pagination passed within its parameters.

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /streams/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"Updated stream"}'
https://vidbeo.com/api/v1/streams/abcdefg

Example response

{
    "id": "sabcdefg",
    "accountId": "abcde",
    "title": "Updated stream",
    "description": null,
    "startTime": "2017-05-01T00:00:00+00:00",
    "endTime": "2017-05-01T01:00:00+00:00",
    "ingestId": "abcde-12345",
    "ingestUrl": "rtmp://ingest-url",
    "ingestKey": "stream",
    "imageFiles": [
        {
            "type": "poster",
            "width": 852,
            "height": 480,
            "name": "abcdefj_480p.jpg",
            "url": "https://url.jpg",
            "fileSize": 1234,
            "imageCodec": "jpg",
            "label": "480p"
        }
    ],
    "videoFiles": [
        {
            "name": "index.m3u8",
            "url": "https://path/index.m3u8",
            "videoCodec": "h264",
            "audioCodec": "aac",
            "fileSize": 0,
            "label": "hls"
        }
    ],
    "playerId": "labcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/w/sabcdefg",
    "encoderId": "eabcdefgh",
    "enabled": true,
    "inGroups": null,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-05-10T10:00:00+01:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-05-10T10:00:00+01:00"
}

Updates the attributes of a stream

The body of the request should contain one, or more, attributes that you would like to update for the stream.

Important: Please be very careful when updating. If you update the value for a top-level key, its entire value will be replaced with the data you supply

DELETE /streams/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/streams/abcdefg

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a stream.

POST /streams

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"Example stream","startTime":"2018-05-01T00:00:00+00:00","endTime":"2018-05-01T01:00:00+00:00"}'
https://vidbeo.com/api/v1/streams

Example response

{
    "id": "sabcdefg",
    "accountId": "abcde",
    "title": "Example stream",
    "description": null,
    "startTime": "2017-05-01T00:00:00+00:00",
    "endTime": "2017-05-01T01:00:00+00:00",
    "ingestId": "abcde-12345",
    "ingestUrl": "rtmp://ingest-url",
    "ingestKey": "stream",
    "imageFiles": null,
    "videoFiles": [
        {
            "name": "index.m3u8",
            "url": "https://path/index.m3u8",
            "videoCodec": "h264",
            "audioCodec": "aac",
            "fileSize": 0,
            "label": "hls"
        }
    ],
    "playerId": "labcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/w/sabcdefg",
    "encoderId": "eabcdefgh",
    "enabled": true,
    "inGroups": null,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-05-10T10:00:00+01:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-05-10T10:00:00+01:00"
}

Creates a new stream.

Required parameters

The required parameters are the title, the start time and the end time.

Key Type Description
title String The title the stream is given (1-100 characters)
startTime String The time the stream will start
endTime String The time the stream will end

Optional parameters

Key Type Description
description String The description to give to this stream
playerId String The id of the player the stream should be presented in
restrictionId String The id of the restriction to limit access to the stream
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field can contain your own key,value pairs

POST /streams/search

Example request

Here we are asking the API to return all streams created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/streams/search

Example response

{
  "streams": [
    {
        "id": "sabcdefg",
        "accountId": "abcde",
        "title": "Example stream",
        "description": null,
        "startTime": "2017-05-01T00:00:00+00:00",
        "endTime": "2017-05-01T01:00:00+00:00",
        "ingestId": "abcde-12345",
        "ingestUrl": "rtmp://ingest-url",
        "ingestKey": "stream",
        "imageFiles": [
            {
                "type": "poster",
                "width": 852,
                "height": 480,
                "name": "abcdefj_480p.jpg",
                "url": "https://url.jpg",
                "fileSize": 1234,
                "imageCodec": "jpg",
                "label": "480p"
            }
        ],
        "videoFiles": [
            {
                "name": "index.m3u8",
                "url": "https://path/index.m3u8",
                "videoCodec": "h264",
                "audioCodec": "aac",
                "fileSize": 0,
                "label": "hls"
            }
        ],
        "playerId": "labcdefgh",
        "restrictionId": null,
        "shareUrl": "https://vidbeo.com/w/sabcdefg",
        "encoderId": "eabcdefgh",
        "enabled": true,
        "inGroups": null,
        "tags": null,
        "metadata": null,
        "createdBy": {
            "id": "abcdefg",
            "name": "Example Person",
            "email": "example.person@company.com"
        },
        "createdTime": "2018-05-10T10:00:00+0100",
        "lastModifiedBy": {
            "id": "abcdefg",
            "name": "Example Person",
            "email": "example.person@company.com"
        },
        "lastModifiedTime": "2018-05-10T10:00:00+0100"
    },
    {
    ...
    }
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc"
}

Searches the streams

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those streams which match them all.

Key Type Description
key String The field to search. Accepted values:
title
startTime
endTime
progress
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /streams request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

POST /streams/search/total

Example request

Here we are asking the API to return the number of streams created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/streams/search/total

Example successful response

{
  "count": 123
}

Searches the streams

The difference between this and the request above is - as the URL suggests - that this version only returns the number of matches. Accordingly, pagination and sorting variables should not be passed in the query string as they would not make sense.

Users

You can manipulate the data held about users by making the following requests:

Request Description
GET /users/:id Returns the details of a single user
GET /users Returns the details of all of the users in your account, subject to any filtering or pagination passed within its parameters
PUT /users/:id Updates a user’s attributes
DELETE /users/:id Deletes a user
POST /users Creates a new user
POST /users/search Search the users

GET /users/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/users/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "name": "Test User",
    "email": "test@test.com",
    "twoStepAuthenticationKey": false,
    "preferences": null,
    "notifications": null,
    "contact": [
        "billing"
    ],
    "reports": null,
    "authenticatedBy": "password",
    "roleId": "basic00000",
    "accessGroups": null,
    "enabled": true,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+00:00",
    "lastSignedInTime": null
}

Returns the details of a single user

Response format

Key Type Description
id String The unique identifier given to this user
accountId String A reference identifier for the account the user belongs to
name String Their name (e.g. “John Smith”)
email String Their email address
twoStepAuthenticationKey Boolean Set if they have enabled two-step verification in the admin panel
preferences Object (For future use) The user’s preferences
notifications Array An array of strings listing the events to email the user about
“newVideo”: email when a new video is added to the account
contact Array Subjects the user should be contacted about
authenticatedBy String How the user is authenticated (“password” or “sso”)
roleId String The id of their assigned role
accessGroups Array The ids of groups they can access (default null, all)
enabled Boolean A user can be temporarily disabled so that they can’t log in, but still exist
[Deprecated] createdByUserId String The id of the user who created this user
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the user was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the user
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the user was last modified
lastSignedInTime String The time they last signed in

GET /users

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/users?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
    "users": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "name": "Test app",
            "twoStepAuthenticationKey": false,
            "preferences": null,
            "notifications": null,
            "contact": null,
            "reports": null,
            "authenticatedBy": "password",
            "roleId": "basic00000",
            "accessGroups": null,
            "enabled": true,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+00:00",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+00:00"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc",
    "prevPage":null,
    "nextPage":null
}

Returns the details of all of the users in your account, subject to any filtering or pagination passed within its parameters

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /users/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"name":"New Name"}'
https://vidbeo.com/api/v1/users/abcdefg

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "name": "New Name",
    "email": "test@test.com",
    "twoStepAuthenticationKey": false,
    "preferences": null,
    "notifications": null,
    "contact": null,
    "reports": null,
    "authenticatedBy": "password",
    "roleId": "basic00000",
    "accessGroups": null,
    "enabled": true,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+00:00",
    "lastSignedInTime": null
}

Updates the attributes of an user

The body of the request should contain one, or more, attributes that you would like to update for the user. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys

DELETE /users/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/users/abcdefg

Example response

No data will be returned, as the resource has been deleted

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Deletes a user

POST /users

Creates a new user

Required parameters

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"name":"Test user","email":"name@company.com","password","ChooseBetterPassword123"}'
https://vidbeo.com/api/v1/users

Example response

{
    "id": "abcdefg",
    "accountId": "abcd",
    "name": "Test user",
    "email": "x@y.com",
    "twoStepAuthenticationKey": false,
    "preferences": null,
    "notifications": null,
    "contact": null,
    "reports": null,
    "authenticatedBy": "password",
    "roleId": "basic00000",
    "accessGroups": null,
    "enabled": true,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T00:01:23+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T00:01:23+00:00",
    "lastSignedInTime": null
}

You must provide their name, email and choose a password. The password must be at least 9 characters and contain at least one uppercase letter, at least one lowercase letter and at least one number.

Key Type Description
name String The name of the new user
email String Their email address
password String Their initial password

Optional parameters

Key Type Description
roleId String The id of the new user’s role
authenticatedBy String Defaults to “password”

POST /users/search

Example request

Here we are asking the API to return all users created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/users/search

Example response

{
    "users": [
        {
            "id": "abcdefg",
            "accountId": "abcd",
            "name": "Test app",
            "email": null,
            "twoStepAuthenticationKey": false,
            "preferences": null,
            "notifications": null,
            "contact": null,
            "reports": null,
            "authenticatedBy": "password",
            "roleId": "basic00000",
            "accessGroups": null,
            "enabled": true,
            "createdBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "createdTime": "2018-01-23T00:01:23+00:00",
            "lastModifiedBy": {
                "id": "abcdefg",
                "name": "Example Person",
                "email": "example.person@company.com"
            },
            "lastModifiedTime": "2018-01-23T00:01:23+00:00"
        },
        ...
    ],
    "page": 0,
    "perPage": 100,
    "sortBy": "createdTime",
    "sortDirection": "desc"
}

Searches the users

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those users which match them all.

Key Type Description
key String The field to search. Accepted values:
name
email
enabled
roleId
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /users request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

Videos

You can manipulate the videos within your account by making the following requests:

Request Description
GET /videos/:id Get the details of one video
GET /videos Get the details of multiple videos
PUT /videos/:id Update a video
DELETE /videos/:id Delete a video
POST /videos Create a video
POST /videos/search Search the videos
POST /videos/search/total Search the videos (returning the total number of matches)
GET /videos/count Count the videos

GET /videos/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/videos/abcdefg

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "title": "Example video",
    "description": null,
    "duration": 30,
    "sourceFile": {
        "name": "example_video.mp4",
        "width": 1280,
        "height": 720,
        "videoCodec": "h264",
        "audioCodec": "aac"
    },
    "imageFiles": [
        {
            "name": "abcdefgh_source.jpg",
            "url": "https://example.com/path/abcdefgh_source.jpg",
            "imageCodec": "jpg",
            "fileSize": 12345,
            "label": "source",
            "type": "source",
            "width": 1280,
            "height": 720
        }
    ],
    "videoFiles": [
        {
            "name": "abcdefgh_480p_h264.mp4",
            "url": "https://example/abcdefg_480p_h264.mp4",
            "videoCodec": "h264",
            "audioCodec": "aac",
            "fileSize": 12345,
            "label": "480p"
        },
        ...
    ],
    "filePrefix": "qrstuvwxyz",
    "captions": [
        "abcdefgh",
        ...
    ],
    "overlays": [
        "abcdefgh",
        ...
    ],
    "playerId": "abcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/...",
    "categories": null,
    "expiryTime": null,
    "enabled": true,
    "version": 1,
    "frame": null,
    "drm": null,
    "isPreroll": false,
    "containsPreroll": false,
    "projection": null,
    "encoderId": "abcdefgh",
    "encodePercentage": 100,
    "encodeRenditions": null,
    "progress": "completed",
    "inGroups": null,
    "tags": [
        "something",
        "else"
    ],
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T01:23:45+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T01:23:45+00:00"
}

Note: The keys returned in the response will vary depending upon its progress - and whether it is enabled - since the data is either not available to return, or should not be made available at all

For example if a video has only just been uploaded and is still waiting to be processed, you may receive only a subset of the data.

Get the details of one video

Response format

Key Type Description
id String The unique identifier given to this video
accountId String A reference identifier for the account the video belongs to
title String The title given to this video
description String The description given to this video
duration Number The video’s duration, in seconds
[Deprecated] filePrefix String A unique prefix used within file paths generated for this video
sourceFile Object Details of the video originally uploaded (information is added during the encoding process)
imageFiles Array Image(s) used to represent the video. There will normally be one, extracted at “source” size
videoFiles Array The generated versions of the uploaded video file, once it has been through the encoding process
captions Array Each element is the id of a set of captions available for this video
overlays Array Each element is an object containing the details of a single overlay
playerId String The id of the player the video should be shown in
restrictionId String A video will be public by default. However access can be restricted by IP and/or country by applying a restriction to it
shareUrl String A URL that can be shared to watch this video
categories Array An optional array of categories (selected from those listed within categories)
expiryTime String The date and time its embed code should expire (usually null)
enabled Boolean A video can be temporarily disabled to block access to it rather than deleting it
version Number Incremented if a video is replaced, for reference
frame String If a custom frame is requested, this temporarily holds that timecode (MM:SS)
drm Object If the video is protected using DRM, this holds internal reference data, such as the kid
isPreroll Boolean Is this video a pre-roll (a short clip, designed to be shown in front of other videos)?
containsPreroll Boolean Does this video already contain a pre-roll (as its first few seconds)?
projection String If the video was filmed in 360 degress, this will be ‘equirectangular’
encoderId String The id of the encoder used to encode the video’s files
encodePercentage Int The percentage encoded (will be 100 once completed)
encodeRenditions Object Which versions did the encoder specify? Populated once encoding progresses
progress String The video’s encoding progress. This can be either “waiting”, “processing”, “completed” or “failed”
inGroups Array If not null/empty, each element is the id of a group
tags Array Each element is a tag
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field returns your own key,value pairs
[Deprecated] createdByUserId String The id of the user who uploaded the video
createdBy Object The ID, name and email of the user who created this (if known)
createdTime String The date and time the video was created
[Deprecated] lastModifiedByUserId String The id of the user who last modified the video
lastModifiedBy Object The ID, name and email of the user who who last modified this (if known)
lastModifiedTime String The date and time the video was last modified

GET /videos

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/videos?page=0&perPage=100&sortBy=createdTime&sortDirection=desc

Example response

{
  "videos": [
    {
      "id": "abcdefgh",
      "accountId": "abcde",
      "title": "Example video",
      "description": null,
      "duration": 30,
      "sourceFile": {
          "name": "example_video.mp4",
          "width": 1280,
          "height": 720,
          "videoCodec": "h264",
          "audioCodec": "aac"
      },
      "imageFiles": [
          {
              "name": "abcdefgh_source.jpg",
              "url": "https://example.com/path/abcdefgh_source.jpg",
              "imageCodec": "jpg",
              "fileSize": 12345,
              "label": "source",
              "type": "source",
              "width": 1280,
              "height": 720
          }
      ],
      "videoFiles": [
          {
              "name": "abcdefgh_480p_h264.mp4",
              "url": "https://example/abcdefg_480p_h264.mp4",
              "videoCodec": "h264",
              "audioCodec": "aac",
              "fileSize": 12345,
              "label": "480p"
          },
          ...
      ],
      "filePrefix": "qrstuvwxyz",
      "captions": [
          "abcdefgh",
          ...
      ],
      "overlays": [
          "abcdefgh",
          ...
      ],
      "playerId": "abcdefgh",
      "restrictionId": null,
      "shareUrl": "https://vidbeo.com/...",
      "categories": null,
      "expiryTime": null,
      "enabled": true,
      "version": 1,
      "frame": null,
      "drm": null,
      "isPreroll": false,
      "containsPreroll": false,
      "projection": null,
      "encoderId": "abcdefgh",
      "encodePercentage": 100,
      "encodeRenditions": null,
      "progress": "completed",
      "inGroups": null,
      "tags": [
          "something",
          "else"
      ],
      "metadata": null,
      "createdBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "createdTime": "2018-01-23T01:23:45+00:00",
      "lastModifiedBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "lastModifiedTime": "2018-01-23T01:23:45+00:00"
    },
    ...
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc",
  "prevPage":null,
  "nextPage":null
}

Returns the details of all of the videos in your account, subject to any pagination passed within its parameters.

Optional parameters

Name Type Default Information
page Integer 0 The index starts at 0
perPage Integer 100 A value between 1 and 100
sortBy String “createdTime” Accepted values:
“createdTime”
“lastModifiedTime”
sortDirection String “desc” Accepted values:
“asc”
“desc”

PUT /videos/:id

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X PUT
-d '{"title":"New title", "description":"New description"}'
https://vidbeo.com/api/v1/videos/abcdefg

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "title": "New title",
    "description": "New description",
    "duration": 30,
    "sourceFile": {
        "name": "example_video.mp4",
        "width": 1280,
        "height": 720,
        "videoCodec": "h264",
        "audioCodec": "aac"
    },
    "imageFiles": [
        {
            "name": "abcdefgh_source.jpg",
            "url": "https://example.com/path/abcdefgh_source.jpg",
            "imageCodec": "jpg",
            "fileSize": 12345,
            "label": "source",
            "type": "source",
            "width": 1280,
            "height": 720
        }
    ],
    "videoFiles": [
        {
            "name": "abcdefgh_480p_h264.mp4",
            "url": "https://example/abcdefg_480p_h264.mp4",
            "videoCodec": "h264",
            "audioCodec": "aac",
            "fileSize": 12345,
            "label": "480p"
        },
        ...
    ],
    "filePrefix": "qrstuvwxyz",
    "captions": [
        "abcdefgh",
        ...
    ],
    "overlays": [
        "abcdefgh",
        ...
    ],
    "playerId": "abcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/...",
    "categories": null,
    "expiryTime": null,
    "enabled": true,
    "version": 1,
    "frame": null,
    "drm": null,
    "isPreroll": false,
    "containsPreroll": false,
    "projection": null,
    "encoderId": "abcdefgh",
    "encodePercentage": 100,
    "encodeRenditions": null,
    "progress": "completed",
    "inGroups": null,
    "tags": [
        "something",
        "else"
    ],
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T01:23:45+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T01:23:45+00:00"
}

Update a video.

The body of the request should contain one, or more, attributes that you would like to update for the video. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.

DELETE /videos/:id

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-X DELETE
https://vidbeo.com/api/v1/videos/abcdefg

Example response

No data will be returned, as the resource has been deleted.

Note: A HTTP status code of 204 will be returned, which means No Content, instead of the usual 200.

Delete a video.

POST /videos

Example request

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '{"title":"New title", "sourceFile":{"name":"xyz.mp4","url":"http://abc.com/xyz.mp4"}}'
https://vidbeo.com/api/v1/videos

Example response

{
    "id": "abcdefgh",
    "accountId": "abcde",
    "title": "New title",
    "description": null,
    "duration": 0,
    "sourceFile": {
        "name": "xyz.mp4"
    },
    "imageFiles": null,
    "videoFiles": null,
    "filePrefix": "qrstuvwxyz",
    "captions": null,
    "overlays": null,
    "playerId": "abcdefgh",
    "restrictionId": null,
    "shareUrl": "https://vidbeo.com/...",
    "categories": null,
    "expiryTime": null,
    "enabled": false,
    "version": 0,
    "frame": null,
    "drm": null,
    "isPreroll": false,
    "containsPreroll": false,
    "projection": null,
    "encoderId": "abcdefgh",
    "encodePercentage": 0,
    "encodeRenditions": null,
    "progress": "waiting",
    "inGroups": null,
    "tags": null,
    "metadata": null,
    "createdBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "createdTime": "2018-01-23T01:23:45+00:00",
    "lastModifiedBy": {
        "id": "abcdefg",
        "name": "Example Person",
        "email": "example.person@company.com"
    },
    "lastModifiedTime": "2018-01-23T01:23:45+00:00"
}

The most important attribute returned is id. This is the unique identifier that this video has now been assigned. You can then use this, via a GET request to the /videos/:id method (see above) to get the details of this video. You will see that its progress attribute will update to be “completed” once the video has successfully encoded (it will initially be “waiting”)

Create a video.

A video needs to be transcoded before it is available to watch. Following the initial POST, the video will be assigned a unique id and placed in a “waiting” state.

Once it is picked up for processing, the system will attempt to download the source file from the provided “url” value. If it can do so, it will verify the file. Assuming it is a supported format, it will then be transcoded into various formats to make it suitable for delivery over the web. A frame will be extracted to represent it too.

Once this process completes, the video will be marked as being ready and it will become available to watch.

Required parameters

The only required parameters are the title the video should be given, and the details of its source file. The source file object must have two attributes: a name, and a url from where our system can access it.

Key Type Description
title String The title the video is given (1-100 characters)
sourceFile Object The video file. It must contain two keys:
name e.g. xyz.mp4
url e.g. http://your-site.com/path/xyz.mp4

Optional parameters

Key Type Description
description String The description to give to this video
playerId String The id of the player the video should be presented in
restrictionId String The id of the restriction to limit access to the video
metadata Object There are often applications that need to record custom data and where none of our existing keys are suitable. This field can contain your own key,value pairs

POST /videos/search

Example request

Here we are asking the API to return all videos created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/videos/search

Example response

{
  "videos": [
    {
      "id": "abcdefgh",
      "accountId": "abcde",
      "title": "Example video",
      "description": null,
      "duration": 30,
      "sourceFile": {
          "name": "example_video.mp4",
          "width": 1280,
          "height": 720,
          "videoCodec": "h264",
          "audioCodec": "aac"
      },
      "imageFiles": [
          {
              "name": "abcdefgh_source.jpg",
              "url": "https://example.com/path/abcdefgh_source.jpg",
              "imageCodec": "jpg",
              "fileSize": 12345,
              "label": "source",
              "type": "source",
              "width": 1280,
              "height": 720
          }
      ],
      "videoFiles": [
          {
              "name": "abcdefgh_480p_h264.mp4",
              "url": "https://example/abcdefgh_480p_h264.mp4",
              "videoCodec": "h264",
              "audioCodec": "aac",
              "fileSize": 12345,
              "label": "480p"
          },
          ...
      ],
      "filePrefix": "qrstuvwxyz",
      "captions": [
          "abcdefgh",
          ...
      ],
      "overlays": [
          "abcdefgh",
          ...
      ],
      "playerId": "abcdefgh",
      "restrictionId": null,
      "shareUrl": "https://vidbeo.com/...",
      "categories": null,
      "expiryTime": null,
      "enabled": true,
      "version": 1,
      "frame": null,
      "drm": null,
      "isPreroll": false,
      "containsPreroll": false,
      "projection": null,
      "encoderId": "abcdefgh",
      "encodePercentage": 0,
      "encodeRenditions": null,
      "progress": "completed",
      "inGroups": null,
      "tags": [
          "something",
          "else"
      ],
      "metadata": null,
      "createdBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "createdTime": "2018-01-23T01:23:45+00:00",
      "lastModifiedBy": {
          "id": "abcdefg",
          "name": "Example Person",
          "email": "example.person@company.com"
      },
      "lastModifiedTime": "2018-01-23T01:23:45+00:00"
    },
    ...
  ],
  "page": 0,
  "perPage": 100,
  "sortBy": "createdTime",
  "sortDirection": "desc"
}

Searches the videos

The parameters to search by are sent as an array of objects. Each object should have three attributes: the key to search, the comparison to make, and the value to compare it to. If multiple objects are sent, an AND search will be done, returning those videos which match them all.

Key Type Description
key String The field to search. Accepted values:
title
enabled
version
progress
playerId
restrictionId
createdTime
comparison String The comparison to make against the value. Accepted values:
eq (equals)
lt (less-than)
lte (less-than-or-equals)
gt (greater-than)
gte (greater-than-or-equals)
lk (like)
is (null)
value Various The value to match the field against

In addition, sorting and pagination can be applied just as it is for the GET /videos request documented above. So you can send page, perPage, sortBy and sortDirection parameters in the query string.

POST /videos/search/total

Example request

Here we are asking the API to return the number of videos created since 1st January 2014. So we need an array containing one object. It should have the key createdTime, the comparison gte (greater-than-or-equals) and the value as the date.

curl
-g
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
-H "Content-Type: application/json"
-X POST
-d '[{"key":"createdTime","comparison":"gte","value":"2014-01-01"}]'
https://vidbeo.com/api/v1/videos/search/total

Example response

{
  "count": 123
}

Searches the videos.

The difference between this and the request above is - as the URL suggests - that this version only returns the number of matches. Accordingly, pagination and sorting variables should not be passed in the query string as they would not make sense.

GET /videos/count

Example request

curl
-H "X-Auth-Email:YOUR-EMAIL"
-H "X-Auth-Key:YOUR-API-KEY"
https://vidbeo.com/api/v1/videos/count

Example response

{
    "count": 123
}

A request to GET /videos will return multiple results. However you might be interested to know how many videos there are in total, to assist with pagination.

The Player API

This is the code needed to permit your page to interact with our page (as mentioned in Step 3)

Note: if it is not shown, make sure you have ‘JAVASCRIPT’ chosen using the top tab

(function (vpJS, undefined) {
    /*
     * The domain used by embedded players
     * 
     * @type {String}
     */
    var iframeDomain = "https://vidbeo.com";
    
    /*
     * Initialise the player API for communicating with the iframes containing embedded players
     *
     * @method init
     * @private
     */
    function init() {
        // attach an event listener for messages sent to this page by any iframe ...
        if (window.addEventListener) {
            window.addEventListener("message", receivedMessage, false);
        }
    };
    
    /*
     * A message has been received by this page
     *
     * @method receivedMessage
     * @param {Object} message
     * @return {}
     * @private
     */
    function receivedMessage(message) {
        // check this message came from an embedded player
        if (message.origin != iframeDomain) {
            return false;
        }
 
        var messageData = message.data;
 
        var messageObject = JSON.parse(messageData);
        if (messageObject == null) {
            return false;
        }
 
        // are all of the expected attributes present?
        if (!messageObject.hasOwnProperty('type') || !messageObject.hasOwnProperty('functionName') || !messageObject.hasOwnProperty('functionParameter')) {
            return false;
        }
        
        // check the type is supported
        if (messageObject.type != "callback") {
            return false;
        }
        
        var alphaNumericRegEx = /^([a-zA-Z0-9]+)$/;
        if (alphaNumericRegEx.test(messageObject.functionName) === false) {
            return false;
        }

        // proceed to call it
        var callback = new Function(messageObject.functionName+'('+messageObject.functionParameter+')');
        callback();
    };
    
    /*
     * Make a request to a player embedded in an iframe on this page
     *
     * @method request
     * @param {String} iframeId
     * @param {String} functionName
     * @param {Object} functionParameter
     * @param {String} callbackName
     * @return {}
     * @public
     */
    vpJS.request = function(iframeId, functionName, functionParameter, callbackName) {
        if (typeof JSON.stringify !== 'function') {
        // it is not possible to send the message without JSON support
            return false;
        }
        
        // build the message as an object which will then be sent JSON-encoded
        var messageObject = {};
        messageObject.functionName = functionName;
        messageObject.functionParameter = typeof functionParameter !== 'undefined' ? functionParameter : null;
        messageObject.callbackName = typeof callbackName !== 'undefined' ? callbackName : null;
        
        var message = JSON.stringify(messageObject);
        
        // send the message
        var iframe = document.getElementById(iframeId);
        iframe.contentWindow.postMessage(message, iframeDomain);
    };
    
    init();
})(window.vpJS = window.vpJS || {});

If you would like to control a player that has been embedded on your own site you can use our Player API.

If you can’t find anything, please get in touch and we’ll try to help where we can. You can use the contact form on our main website, or email us directly at support@vidbeo.com.

Please follow the steps below to get started.

Step 1

To use the Player API, you will first need to enable it, since the player assumes it is not needed.

Click on ‘Content’ in the main menu within the admin panel, then on ‘Players’.

You should now see all of the players in your account. Click on the one you would like to enable the Player API for.

You should now see a page showing that player’s details. Scroll down the page until you see a menu labelled ‘Player API’. When asked whether you would like to enable it, select Yes. In addition, you need to specify what domain(s) you would like to use the Player API on. Enter them in the following box, separated by a comma. For example:

https://mycompany.com,https://www.something.com.

Click once on the ‘Save changes’ button and if successful, the Player API will now be enabled for that player.

This means that that particular player will now start to listen for requests from the domain(s) you provided - and be able to send messages to them.

Step 2

If you have not embedded one of our players on your site, do that next: sign in to your admin panel, click on the thumbnail image for one of your videos and you will be shown its details. On that page you should see a section called ‘Embed’. This will contain our embed code.

Copy and paste that whole bit of code on to your page where you want the video to appear, refresh, and you should see the player.

Step 3

Currently your Player API requests will fail because your browser will block them. That’s because your page and our page are on different domains.

We have made a simple vpJS.request function to permit your browser to send messages to our player. That is shown to the right. Please copy that block of code and save it as a file (for example called vp.js just to make it clear what it is).

That file needs to be included on any page you will be using our Player API on, so you might want to include it in a header/footer template. You only need to include it once on a page.

Try it out

We will start by demonstrating the simplest action: play.

Note: Normally you would be listening for a click event. This is just a very simple example to demonstrate the concept!

Just after the player, put this line of HTML:

<a href="#play" onclick="vpJS.request('vp_iframe_VIDEOID', 'play');">Play Video</a>

… making sure to replace VIDEOID with the actual id of your embedded object. If you are not sure what it is, simply look at the start of your embed code. This starts with an iframe tag whose id is, for example, vp_iframe_abcdefghi. In that case the id to use is abcdefghi.

Now let’s look at the components of that function call set to run when ‘Play Video’ is clicked:

vpJS

This is just short for Vidbeo Player JS.

request

This is the name of the function the library makes available - and through which interaction with the player is done.

vp_iframe_VIDEOID

This is needed in order for the library to know which element (the iframe) the message should be sent to.

play

This is the action you want to perform using the Player API. Here we want to play the video.

Note: Two more parameters are supported (not included here because they are not applicable to the play action). Those are the parameter to pass to the action (for example the new volume, in the case of the volume action), and finally the name of a callback function.

So now if you refresh the page, you should hopefully see a link somewhere near the player on your page called ‘Play Video’. Click on it. Does the video start playing?

If so, great. Please now read through the following sections to learn more about how the Player API works and what you can do with it.

Structure

All requests follow the same basic structure:

vpJS.request(elementId,action,parameter, callback);

Actions

We have currently exposed a limited number of our available functions. If you need more, please get in touch.

Action Description
play Plays the player
pause Pauses the player
currentTime Gets/sets the current time, in seconds
volume Gets/sets the volume, as a decimal

play

Example request

This tells the player API to play the object with id ‘abcdefg’.

vpJS.request('vp_iframe_abcdefg', 'play');

Plays the player.

pause

Example request

This tells the player API to pause the object with id ‘abcdefg’.

vpJS.request('vp_iframe_abcdefg', 'pause');

Pauses the player.

currentTime

Gets/sets the current time, in seconds.

Since this function can be used to get and set the current time, there are two different ways it can be used:

SET

Example request

This tells the player API to change the current time of the object with id ‘abcdefg’ to 10 seconds:

vpJS.request('vp_iframe_abcdefg', 'currentTime', 10);

If you would like to set the current time, you will need to pass that time (in seconds) as the third parameter in the request:

Parameter Type Description
time Number The time in seconds the player should seek to
callback String N/A (null)

GET

Example request

Please take a look at the Callbacks section to see how the referenced responseHandler function (you can choose a different name) works:

vpJS.request('vp_iframe_abcdefg', 'currentTime', null, 'responseHandler');

If you would like to get the current time, it works slightly differently. You need to provide the name of a function for the time to be sent to (as part of a object our player builds). Ideally you would be able to get the time directly, however this is not possible because messages are asynchronous (essentially the browser does not wait for a response).

Parameter Type Description
time Number N/A (null)
callback String The name of the callback function

volume

Gets/sets the current volume, as a decimal.

Since this function can be used to get and set the volume, there are two different ways it can be used:

SET

Example request

This tells the player API to change the volume of the object with id ‘abcdefg’ to 0.5 (50%):

vpJS.request('vp_iframe_abcdefg', 'volume', 0.5);

If you would like to set the volume, you will need to pass that volume (as a decimal) as the third parameter in the request:

Parameter Type Description
volume Number The new volume
callback String N/A (null)

GET

Example request

Please take a look at the Callbacks section to see how the referenced responseHandler function (you can choose a different name) works:

vpJS.request('vp_iframe_abcdefg', 'volume', null, 'responseHandler');

If you would like to get the volume, it works slightly differently. You need to provide the name of a function for the volume to be sent to (as part of a object our player builds). Ideally you would be able to get the volume directly, however this is not possible because messages are asynchronous (essentially the browser does not wait for a response).

Parameter Type Description
volume Number N/A (null)
callback String The name of the callback function

Callbacks

To illustrate how the callback works, here is a very basic function that could be used to receive any kind of information sent by the player (in reality you would add more validation - and not simply output to the console!). If you recall from the Actions section, in our examples we passed the name as ‘responseHandler’. As such, our function is called ‘responseHandler’.

function responseHandler(response) {
    console.log(response);
    
    switch (response.type) {
        case 'volume':
            console.log('Embedded player '+response.embedId+' has a volume of '+response.value);
            break;
            
        ...
    }
}

The first line of the function simply logs to the console the response object without checking it. Which would result in a line like this:

Object {embedId: "abcdefghi", currentId: "abcdefghi", type: "volume", value: 0.5}

… and the second line contains a simple switch that checks the type. In this case, it is simply looking for a response to the ‘volume’ action. If it sees one, it logs that to the console, reporting the value received.

Whenever the player API needs to send information to the page that a player has been embedded on, it does that by calling a function whose name you specify (it must be alphanumeric).

If you have already read the documentation for the available Actions you will see that all of the ‘get’ actions require you to pass the name of a function in order to receive a response from them. That is because your browser will not wait for a response to that request for information (for example if you request the current time). So it needs to be sent in response to that request.

The function should expect a single parameter. This is sent as an object with four attributes:

Parameter Value
embedId The id of the embedded object, as a string. This is passed since you might have multiple players embedded on the same page, and will need to know from which the data was sent
currentId The id of the currently loaded object, as a string.If the embedded object is a video, then this will always be the same as the value of the first parameter and so you can ignore itIf the embedded object is a playlist (with more than one video in) then this value will change, since the loaded video will change.
type What is being sent. Normally this will be the name of the action that requested it. For example ‘volume’
value The value being sent. For example in response to a request for the volume, it might be 0.5

Issues

In an ideal world, every browser on every device would behave the same. Unfortunately they do not. The following list contains issues you should be aware of when using our Player API.

Volume controls unavailable

Unfortunately both iOS and Android (which power the majority of tablets and smartphones) prevent you from setting the volume of a video element embedded on a web page. This is why we do not show the volume control in our player.

This means if you use the ‘volume’ action yourself, the call will fail. The ‘volume’ action will also return an unreliable value, if it returns one at all, since the volume our player thinks it has been set to may not actually be the real one. The event that informs the player of the current volume is not sent.

There is no indication this situation will change, since it is still the case with the latest versions of Android and iOS.