Get started

​

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:

​

HTTP response codes

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

​

Authorization

To make any request you will need an API key. To get one you will need:

• An account with us to manage your billing. You can sign up using our dashboard: https://dash.vidbeo.com/signup.
• The Video API to be enabled for your account. Please get in touch.
• The role of owner (the first user in any account always has this role).

On our dashboard, the API keys page is within the More menu. A key is only shown once, so make a note of it and keep it secret. Your API key should be treated just like a password.

That API key should be passed in a header like this:

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

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). For example:

{
  "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 thing. For example PHP’s Guzzle or NodeJS’s Got.

​

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 object in the errors array:

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

​

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:

2022-01-01T12:00:00.000Z

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

2022-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 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:

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 two 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.