Video API

Use our video API to handle your video storage, transcoding and delivery.

We recommend reading all of the information below. If you have any questions or indeed need anything that we don't currently provide, please don't hesitate to get in touch at https://www.vidbeo.com/contact. We'll do our best to help.

Note: This site documents API V2. If you require assistance with our legacy API V1 or transitioning over to API V2, please get in touch.

Structure

Video API requests are made to a URI that follows this basic structure:

https://api.vidbeo.com/v2/resource/[parameters]

HTTP methods

Each API request uses one of the following HTTP methods. Generally you will use:

MethodAction
GETUsed to get data about resources
POSTUsed to create a new resource
PATCHUsed to update a resource. Any top-level attributes not included in your request will be left unchanged
DELETEUsed to delete a resource

Authorization

To make any request you will need an API key.

To get one you will need to have:

  • an account with us to manage your billing (if not please sign up using our dashboard: https://dash.vidbeo.com/signup)
  • the role of owner (which the first user in any account always has)

The API keys page is within the Developers menu of our dashboard. Click the link on that page to request a new API key. Give it a name. It will be shown once so make a note of it and keep it secret. Your API key should be treated just like a password. If you do not see that option, the video API may not be enabled.

Armed with an API key you should now be able to try out the video API. Start by trying an example request (to get videos):

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/videos"

If your API key is valid you should get a JSON response object back, with HTTP status code 200 (which means success). It will not actually contain any videos if you have not uploaded any yet. But this just tests everything is working:

{
"success": true,
"result": [],
"links": null,
"errors": []
}

On the other hand if your API key is not valid, you should get an error response back (with an equivalent error HTTP status code, like 401 or 403). Such as:

{
"success": false,
"result": null,
"links": null,
"errors": [
{
"message": "Invalid key value"
}
]
}

In our examples we will use the command-line tool curl as that makes it easy to illustrate how the requests are structured . However you will likely use a HTTP request library in your chosen language to do the same things. For example PHP's Guzzle or NodeJS's Got.

Response codes

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

CodeMeaning
200The request was successful
400The 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
401The request could not be authorised. If you get this response code, please check that you are sending an API key
403The request is forbidden. The API key used is either invalid or does not permit that action. If you get this response code, please check that you are accessing a resource you have been granted access to and are using https
404The requested endpoint or resource could not be found. If you get this response code when trying to access an individual object, perhaps it has been deleted?
429The request could not be processed because too many requests have been made. If you get this response code, you may have hit our rate-limit or our system is under load. Please wait for a period of time before making another request
500There is a temporary problem with the API which resulted in an error
503There 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.

Payload/response

Payloads and responses must be formatted as JSON. Please use the Content-Type and Accept headers when sending/receiving JSON:

Content-Type: application/json

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, the HTTP status code will indicate the problem (for example a 400 code generally means there was a problem with the data sent). In the response object we will set success as false and should include at least one error in the errors array:

{
"success": false,
"result": null,
"links": null,
"errors": [
{
"message": "Unexpected field sent in request body"
}
]
}

If we know a specific field in a POST or PATCH request was invalid, we will put its name in brackets to make the error message easier to parse by your application. For example:

{
"success": false,
"result": null,
"links": null,
"errors": [
{
"message": "[name] This field is required"
},
{
"message": "[description] This field must be a string"
}
]
}

CORS

Our video API does not support client-side Cross Origin Resource Sharing (CORS). It must be used server-side.

Date format

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

2021-02-01T12:00:00.000Z

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

2021-02-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 for a 2xx status code to check you are not accidentally caching an error.

Passing parameters

Some requests support being passed parameters. For example to paginate the returned data.

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

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

For POST, PATCH and DELETE requests, parameters should be passed within the body of the request (as JSON). Make sure to send the correct headers:

Content-Type: application/json

Accept: application/json

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 pagination values are passed in the URL's query string. Endpoints that support pagination generally expect these two variables:

VariableTypeDescription
limitIntThe number to return per page
cursorStringA long string of characters which tells our system where to start the next requst from

You may have seen cursor-based pagination before, such as in the Slack API. It is more efficient than an offset-based approach.

You can initially send a limit. For example ?limit=5.

And then if the response contains a links object which has a next key, that's the URL to use for your next API request to get the next page of results. That link will include a cursor. For example it may end like: ...?limit=5&cursor=a-long-value.

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

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

2) You can check whether the response contains a links object that contains a next key.

The exception in both these cases is when the number of results happens to match the number requested per page. For example if you ask for a limit of 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 links.next URL may be built, in case. Upon requesting that next URL, it is at that point that you will know (since its result array will be empty).

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.

Ready

The most common use of the API is to add a video. You do that using POST /videos