# Developer documentation
Source: https://developers.vidbeo.com/introduction

Documentation for our APIs

<CardGroup>
  <Card title="Video API" href="/video-api/get-started">
    Use our Video API to handle your video storage, transcoding and delivery.
  </Card>

  <Card title="Player API" href="/player-api/get-started">
    Use our Player API to control a player embedded on your website.
  </Card>
</CardGroup>


# Get started
Source: https://developers.vidbeo.com/player-api/get-started

Use our Player API to control the player using JavaScript

## 1. Add it

Since your page and our embed code are on different domains, you need to add some additional JavaScript to use it:

```html theme={null}
<script src="https://player.vidbeo.com/sdk/api.js"></script>
```

## 2. Initialise it

*Either* pass the HTML element ID as the first parameter:

```html theme={null}
<div id="your_element_id"></div>

<script>
let player = new Vidbeo.Player("your_element_id", {
  id: "your_video_id",
  width: 1280,
  height: 720
});
</script>

</body>
```

*Or* you could do the same with an event listener:

```html theme={null}
<div id="your_element_id"></div>

<script>
  document.addEventListener("DOMContentLoaded", function(event) {
    let player = new Vidbeo.Player("your_element_id", {
      id: "your_video_id",
      width: 1280,
      height: 720
    });
  }
</script>
```

*Or* you might like to use the Player API to control an existing player. In which case you need to pass a *reference* to that HTML element as the first parameter. For example:

```html theme={null}
<iframe src="..." allowfullscreen></iframe>

<script>
  let iframe = document.querySelector("iframe");
  let player = new Vidbeo.Player(iframe);
</script>
```

There are a variety of [options](/player-api/v1/reference/options) available. The examples above were deliberately kept simple.

## 3. Try it

Check the player is ready. That returns a *Promise*. For example:

```javascript theme={null}
player
  .ready()
  .then(function (data) {
    console.log("Player is ready");
  })
  .catch(function (error) {
    console.error("Player is not ready", error);
  });
```

You should see the message appear in your browser's console (usually shown by pressing the F12 key or by opening *Developer Tools*).


# Events
Source: https://developers.vidbeo.com/player-api/v1/reference/events

The events sent by the Player API

These are all the events you can listen for, along with an example of data passed to the callback registered using the [on() callback](/player-api/v1/reference/methods#on-event-string-callback-function).

<Tip>
  Events include some detail about the current state but you can always use the
  **get** methods to return any additional data you need.
</Tip>

| Event              | Data type | Example data passed to callback          |
| ------------------ | --------- | ---------------------------------------- |
| durationchange     | Object    | `{"duration":11.4}   `                   |
| ended              | Object    | `{"seconds":11.4,"percentage":100}`      |
| fullscreenchange   | Object    | `{"fullscreen":true}`                    |
| hotspotclicked     | Object    | `{"id":"abcdefgh12345678","seconds":5}`  |
| loadedmetadata     | Object    | `{"videoWidth":1920,"videoHeight":1080}` |
| pause              | Object    | `{"seconds":7.235,"percentage":63.461}`  |
| play               | Object    | `{"seconds":1.341,"percentage":11.761}`  |
| playing            | Object    | `{"seconds":1.341,"percentage":11.767}`  |
| progress           | Object    | `{"percentage":100}`                     |
| qualitychange      | Object    | `{"quality":"720p"}`                     |
| playbackratechange | Object    | `{"playbackRate":1.5}`                   |
| seeked             | Object    | `{"seconds":5,"percentage":43.86}`       |
| seeking            | Object    | `{"seconds":5,"percentage":43.86}`       |
| trackchange        | Object    | `{"language":"en"}`                      |
| timeupdate         | Object    | `{"seconds":7.648,"percentage":67.089}`  |
| volumechange       | Object    | `{"volume":0.82}`                        |


# Methods
Source: https://developers.vidbeo.com/player-api/v1/reference/methods

The methods exposed by the Player API

<Tip>
  Methods return a
  [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
  As shown below, you can handle the response to see if the request succeeded.
</Tip>

### play()

Play the video.

```javascript theme={null}
player
  .play()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### pause()

Pause the video.

```javascript theme={null}
player
  .pause()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### ready()

Check if the player is ready.

<Tip>
  You don't need to chain this yourself when calling other methods as we check
  the player is ready internally.
</Tip>

```javascript theme={null}
player
  .ready()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### requestFullscreen()

Enter fullscreen mode.

Be aware that if you toggle fullscreen mode using an external button, that button will of course be covered up by the player once it goes fullscreen.

```javascript theme={null}
player
  .requestFullscreen()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### exitFullscreen()

Exit fullscreen mode.

```javascript theme={null}
player
  .exitFullscreen()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

## Getters

These are the methods that return a value.

### getColour()

Get the colour of the player, as a six-character hex. A blank value means the default colour is used. The value is a string.

For example:
`74b9ff`

```javascript theme={null}
player
  .getColour()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getCurrentTime()

Get the current time. The value is a number in seconds.

For example:
`11.4`

```javascript theme={null}
player
  .getCurrentTime()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getDuration()

Get the duration of the video, once it's known. It will only be known once the video's metadata is loaded. The value is a number in seconds.

For example:
`12`

```javascript theme={null}
player
  .getDuration()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getEmbed()

Get an embed code for the video. It is a string which is a snippet of HTML.

```javascript theme={null}
player
  .getEmbed()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getEnded()

Check if the video has ended. This is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getEnded()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getFullscreen()

Check if the video is fullscreen. This is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getFullscreen()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getHeight()

Get the height of the video (not the height it is embeddeed at). This is a number.

It is only known once the video's metadata has downloaded.

For example:
`720`

```javascript theme={null}
player
  .getHeight()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getId()

Get the ID of the embedded video. This is a string.

For example:
`abcdefgh1234567`

```javascript theme={null}
player
  .getId()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getLoop()

Check if the video is set to loop (restart when it ends). This is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getLoop()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getMuted()

Check if the video is muted. This is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getMuted()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getPaused()

Check if the video is paused. This is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getPaused()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getPlaybackRate()

Get the playback rate. It's returned as a number. The default is 1 (meaning 1x). The range is 0.5 to 2.

For example:
`0.5`

```javascript theme={null}
player
  .getPlaybackRate()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getPlayed()

Get the time period(s) during which the video has been played. This is a 2D array. All values are in seconds.

For example:
`[[0,4.367],[6,8.738]]`

```javascript theme={null}
player
  .getPlayed()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getProgress()

Get the part(s) of the video that have been buffered. The data is returned as a 2D array with the values in seconds.

For example:
`[[0,8]]`

```javascript theme={null}
player
  .getBuffered()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getQualities()

Get the available qualities/renditions. At a minimum there is an "auto" quality however once the video's metadata is loaded and so the qualities are known, you may want to manually set a particular quality to be used. You would send one of these values. Each value is a string.

For example:
`["360p","720p","1080p","auto"]`

```javascript theme={null}
player
  .getQualities()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getQuality()

Get the currently selected quality/rendition. The default value is "auto" which means it is left up to the player to decide the quality (depending on the connection speed). However you may have manually selected a particular quality. The value is returned as a string.

For example:
`"720p"`

```javascript theme={null}
player
  .getQuality()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getSeekable()

Get the time period(s) that are seekable within. This is a 2D array with each element being an array of *\[start,end]*. All values are in seconds.

For example:
`[[0,11.4]]`

```javascript theme={null}
player
  .getSeekable()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getSeeking()

Is the video *currently* seeking? The value is a boolean.

For example:
`false`

```javascript theme={null}
player
  .getSeeking()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getTracks()

Get the available subtitle/closed caption tracks. This is an array of objects. If the video does not have any tracks, it will be empty.

For example:
`[{"id":"abcdefgh1234567","kind":"captions","language":"en","label":"English","mode":"disabled"}]`

```javascript theme={null}
player
  .getTracks()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getTitle()

Get the title of the embedded video. It is a string.

For example:
`"Example video"`

```javascript theme={null}
player
  .getTitle()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getUrl()

Get a URL to the video that can be shared or emailed. It is a string.

For example:
`"https://watch.vidbeo.com/abcdefghiklmnop"`

```javascript theme={null}
player
  .getUrl()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getVolume()

Get the current volume. It is returned as a number between 0 and 1.

For example:
`0.3`

```javascript theme={null}
player
  .getVolume()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### getWidth()

Get the width of the video. This is only known once the video's metadata has been downloaded. It is returned as a number.

For example:
`1920`

```javascript theme={null}
player
  .getWidth()
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

## Setters

For these methods you need to pass a value as its parameter.

### setColour(colour: String)

Set the colour of the player. We generally use a neutral look which works well on most sites but you can apply an accent colour. It should be a six-character string using the hex format.

For example:
`00ffff`

Any returned data parameter will simply echo back the same colour.

```javascript theme={null}
player
  .setColour("00ffff")
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setCurrentTime(time: Float)

Seek to a particular time. The value should be a time in seconds. It must be greater than 0, and less than the duration of the video

For example:
`7`

Any returned data parameter will simply echo back the same time.

```javascript theme={null}
player
  .setCurrentTime(7)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setLoop(loop: Boolean)

Set whether the video should loop when it ends. The value should be a boolean.

For example:
`true`

Any returned data parameter will simply echo back the same value.

```javascript theme={null}
player
  .setLoop(true)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setMuted(muted: Boolean)

Set whether the video should be muted. The value should be a boolean.

For example:
`true`

Any returned data parameter will simply echo back the same value.

```javascript theme={null}
player
  .setMuted(true)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setPlaybackRate(rate: Float)

Set the playback speed. Since browsers do not reliably support some speeds, currently the value should be one of these numbers: *0.5*, *1*, *1.5*, *2*.

For example:
`1.5`

Any returned data parameter will simply echo back the same value.

```javascript theme={null}
player
  .setPlaybackRate(1.5)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setQuality(quality: String)

Set the quality. The default is "auto" which leaves the player to optimise the quality based on the available connection speed. However you can manually set a quality (from those available, as reported by *getQualities()*) such as "1080p" to override that.

For example:
`1080p`

Any returned data parameter will simply echo back the same value.

```javascript theme={null}
player
  .setQuality("1080p")
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

### setVolume(volume: Float)

Set the volume. It should be a number between 0 and 1.

For example:
`0.5`

Any returned data parameter will simply echo back the same value.

```javascript theme={null}
player
  .setVolume(0.5)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });
```

## Event listener

To listen for one of the [events](/player-api/v1/reference/events) use the *on* method to register a callback function and the *off* method to remove it.

<Tip>Unlike the methods above, these do not return a *Promise*.</Tip>

### on(event: String, callback: Function)

Here we are listening for the *playing* event. The second parameter needs to be a function. That is the callback which is run when that event is fired:

```javascript theme={null}
player.on("playing", function (data) {
  console.log("playing", data);
});
```

### off(event: String, callback: Function)

Here we are no longer listening for the *playing* event and want to remove *all* callbacks:

```javascript theme={null}
player.off("playing");
```

If you want to remove a specific callback function, pass that function as the optional second parameter:

```javascript theme={null}
const onPlaying = function (data) {
  console.log("playing", data);
};
player.off("playing", onPlaying);
```

Find out all of the possible [events](/player-api/v1/reference/events).


# Options
Source: https://developers.vidbeo.com/player-api/v1/reference/options

The options available in the Player API

You should have seen how to initialise the Player API on the [get started](/player-api/get-started) page.

If you recall we created a player like this:

```html theme={null}
<script>
  let player = new Vidbeo.Player("your_element_id", {
    id: "your_video_id",
  });
</script>
```

You can customise the player using the *second* parameter. It supports the following options:

| Option      | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                       |
| ----------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aspectratio | String  | "16:9"  | The aspect ratio the player should show the content at: "16:9", "21:9", "4:3". This applies only if you also set *responsive* as *true*.                                                                                                                                                                                                                          |
| autoplay    | Boolean | false   | Should the video start playing on-load?                                                                                                                                                                                                                                                                                                                           |
| colour      | String  | ''      | A custom colour as a six-character hex such as *"00b894"*                                                                                                                                                                                                                                                                                                         |
| controls    | Boolean | true    | Should controls be shown?                                                                                                                                                                                                                                                                                                                                         |
| buttons     | String  | ''      | If empty, the default buttons will be shown. That's what we recommend. You can override that by specifying a comma-separated string of button names. For example "main\_play,play,progress,fullscreen"                                                                                                                                                            |
| dnt         | Boolean | false   | A 'Do Not Track' option. If set as true, analytics events normally sent by the player will not be sent                                                                                                                                                                                                                                                            |
| height      | Number  | N/A     | If you would like to embed a video at a *fixed* size, provide its height, such as 360                                                                                                                                                                                                                                                                             |
| id          | String  | ''      | You must provide the unique ID of a video to embed: it will look something like *uk1vabcde23445abcde*                                                                                                                                                                                                                                                             |
| jwt         | String  | ''      | A video can be set to require authentication, and you can provide that using a JSON Web Token (JWT). If used, you can provide that token in this field                                                                                                                                                                                                            |
| keyboard    | Boolean | true    | Enable keyboard controls?                                                                                                                                                                                                                                                                                                                                         |
| loop        | Boolean | false   | Should the video restart when it ends?                                                                                                                                                                                                                                                                                                                            |
| muted       | Boolean | false   | Should the video be muted when it loads? You will likely need to set this as true if you set *autoplay* as *true*, as browsers usually block videos from auto-playing that are *not* muted                                                                                                                                                                        |
| playsinline | Boolean | true    | On mobile device, should the video play within the page (rather than automatically move into fullscreen mode)                                                                                                                                                                                                                                                     |
| preload     | Boolean | true    | On desktop (where this can be controlled) should the player buffer a short amount of the video on-load? This improves performance as the video can then start playing immediately *but* if the viewer does *not* play the video, it may waste a little data                                                                                                       |
| quality     | String  | 'auto'  | We use a technique called ABR so that our player will automatically try to play the best quality based on the available connection speed. Which can vary. However on desktop (where this can be controlled) you may want to override that and force it to pick the highest available quality on-load. If so, set this as *"highest"*                              |
| responsive  | Boolean | true    | Most modern sites adapt to the width of the screen to look great on both desktop and mobile. You therefore don't need to set a *width* or *height* value. If you would like to control the responsive behaviour yourself in your own CSS you must set this as *false*. That tells our player *you* will be handling its size and so it should not add its own CSS |
| t           | Number  | 0       | A time in seconds to skip forward to on-load                                                                                                                                                                                                                                                                                                                      |
| title       | Boolean | false   | Should the video's title be shown within the player?                                                                                                                                                                                                                                                                                                              |
| track       | String  | ''      | If your video has subtitles or closed-captions, you may want them turned on immediately on-load. If so, set the language code of the one to use (as you may have multiple ones). For example to enable English captions on-load, set this as *"en"*                                                                                                               |
| width       | Number  | N/A     | If you would like to embed a video at a *fixed* size, provide its width, such as 640                                                                                                                                                                                                                                                                              |

You can control the player using the [methods](/player-api/v1/reference/methods) the Player API exposes.


# Get started
Source: https://developers.vidbeo.com/video-api/get-started

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

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

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

## HTTP response codes

We will generally use the standard [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when returning responses so that your application knows what has happened:

| Code | Meaning                                                                                                                                                             |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | The request was successful                                                                                                                                          |
| 400  | The request was invalid. Please check that you are including *all* required fields and that each value is the correct type                                          |
| 401  | The request could not be authorised. If you get this response code, please check that you are sending a valid API key                                               |
| 403  | The request is forbidden. The API key used is either invalid or does not permit that action on that resource                                                        |
| 404  | The requested endpoint or resource could not be found. If you get this response code when trying to access an individual object, it has likely been deleted         |
| 429  | Too many requests have been made. You may have hit our rate-limit or our system is under load. Please wait for a short 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                                                                                       |

## 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://dashboard.vidbeo.com/signup](https://dashboard.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:

```shell theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://github.com/guzzle/guzzle) or NodeJS's [Got](https://github.com/sindresorhus/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:

```json theme={null}
{
  "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](https://en.wikipedia.org/wiki/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://en.wikipedia.org/wiki/Percent-encoding):

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

| Variable | Type   | Description                                                                            |
| -------- | ------ | -------------------------------------------------------------------------------------- |
| limit    | Int    | The number to return per page                                                          |
| cursor   | String | A 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](https://slack.engineering/evolving-api-pagination-at-slack/). 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.


# Fetch analytics
Source: https://developers.vidbeo.com/video-api/v2/reference/analytics/fetch-analytics

get /analytics
Fetch analytics



# Create API key
Source: https://developers.vidbeo.com/video-api/v2/reference/api-keys/create-api-key

post /keys
Create a new API key



# Delete API key
Source: https://developers.vidbeo.com/video-api/v2/reference/api-keys/delete-api-key

delete /keys/{key_id}
Delete an API key



# Fetch API key
Source: https://developers.vidbeo.com/video-api/v2/reference/api-keys/fetch-api-key

get /keys/{key_id}
Get an API key's details



# List API keys
Source: https://developers.vidbeo.com/video-api/v2/reference/api-keys/list-api-keys

get /keys
Fetch all API keys



# Update API key
Source: https://developers.vidbeo.com/video-api/v2/reference/api-keys/update-api-key

patch /keys/{key_id}
Update an API key's details



# Fetch audit logs
Source: https://developers.vidbeo.com/video-api/v2/reference/audit-logs/fetch-audit-logs

get /audit_logs
Fetch audit logs (only available on an Enterprise Plan)



# Convert trial
Source: https://developers.vidbeo.com/video-api/v2/reference/billing/convert-trial

post /accounts/upgrade/session
Upgrade from a trial to a full, paid account



# Redirect to Stripe
Source: https://developers.vidbeo.com/video-api/v2/reference/billing/redirect-to-stripe

post /accounts/billing/portal
Redirect to Stripe's billing portal



# Create category
Source: https://developers.vidbeo.com/video-api/v2/reference/categories/create-category

post /categories
Create a new category



# Delete category
Source: https://developers.vidbeo.com/video-api/v2/reference/categories/delete-category

delete /categories/{category_id}
Delete a category



# Fetch category
Source: https://developers.vidbeo.com/video-api/v2/reference/categories/fetch-category

get /categories/{category_id}
Get a category's details



# List categories
Source: https://developers.vidbeo.com/video-api/v2/reference/categories/list-categories

get /categories
Fetch all categories



# Update category
Source: https://developers.vidbeo.com/video-api/v2/reference/categories/update-category

patch /categories/{category_id}
Update a category's details



# Add video to folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/add-video-to-folder

post /folders/{folder_id}/videos/{video_id}
Add a video to a folder



# Create folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/create-folder

post /folders
Create a new folder



# Delete folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/delete-folder

delete /folders/{folder_id}
Delete a folder



# Fetch folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/fetch-folder

get /folders/{folder_id}
Get a folder's details



# List folders
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/list-folders

get /folders
Fetch all folders



# List videos in folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/list-videos-in-folder

get /folders/{folder_id}/videos
Get videos in a folder



# Remove video from folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/remove-video-from-folder

delete /folders/{folder_id}/videos/{video_id}
Remove a video from a folder



# Update folder
Source: https://developers.vidbeo.com/video-api/v2/reference/folders/update-folder

patch /folders/{folder_id}
Update a folder's details



# Create identity provider
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/create-identity-provider

post /idps
Create a new identity provider



# Delete identity provider
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/delete-identity-provider

delete /idps/{idp_id}
Delete an identity provider



# Fetch identity provider
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/fetch-identity-provider

get /idps/{idp_id}
Get an identity provider's details



# List identity providers
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/list-identity-providers

get /idps
Fetch all identity providers



# List identity providers (summary)
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/list-identity-providers-summary

get /saml2/accounts/{account_id}/idps
Get a list of identity providers for an account



# Update identity provider
Source: https://developers.vidbeo.com/video-api/v2/reference/identity-providers/update-identity-provider

patch /idps/{idp_id}
Update an identity provider's details



# Create invite
Source: https://developers.vidbeo.com/video-api/v2/reference/invites/create-invite

post /invites
Create a new invite



# Delete invite
Source: https://developers.vidbeo.com/video-api/v2/reference/invites/delete-invite

delete /invites/{invite_id}
Delete an invite



# List invites
Source: https://developers.vidbeo.com/video-api/v2/reference/invites/list-invites

get /invites
Fetch all invites



# Verify invite
Source: https://developers.vidbeo.com/video-api/v2/reference/invites/verify-invite

post /invites/{invite_id}/accept/{invite_token}
Verify a sent invite URL is valid



# Create JWT key
Source: https://developers.vidbeo.com/video-api/v2/reference/jwt-keys/create-jwt-key

post /jwt_keys
Create a new JWT key



# Delete JWT key
Source: https://developers.vidbeo.com/video-api/v2/reference/jwt-keys/delete-jwt-key

delete /jwt_keys/{jwt_key_id}
Delete a JWT key



# Fetch JWT key
Source: https://developers.vidbeo.com/video-api/v2/reference/jwt-keys/fetch-jwt-key

get /jwt_keys/{jwt_key_id}
Get a JWT key's details



# List JWT keys
Source: https://developers.vidbeo.com/video-api/v2/reference/jwt-keys/list-jwt-keys

get /jwt_keys
Fetch all JWT keys



# Reset password
Source: https://developers.vidbeo.com/video-api/v2/reference/password/reset-password

post /users/password/reset
Request a pasword reset



# Set password
Source: https://developers.vidbeo.com/video-api/v2/reference/password/set-password

post /users/{user_id}/password/{token}
Set a new password



# Create player
Source: https://developers.vidbeo.com/video-api/v2/reference/players/create-player

post /players
Create a new player



# Delete player
Source: https://developers.vidbeo.com/video-api/v2/reference/players/delete-player

delete /players/{player_id}
Delete a player



# Fetch player
Source: https://developers.vidbeo.com/video-api/v2/reference/players/fetch-player

get /players/{player_id}
Get a player's details



# List players
Source: https://developers.vidbeo.com/video-api/v2/reference/players/list-players

get /players
Fetch all players



# Update player
Source: https://developers.vidbeo.com/video-api/v2/reference/players/update-player

patch /players/{player_id}
Update a player's details



# Create service
Source: https://developers.vidbeo.com/video-api/v2/reference/services/create-service

post /services
Create a new service



# Delete service
Source: https://developers.vidbeo.com/video-api/v2/reference/services/delete-service

delete /services/{service_id}
Delete a service



# Fetch service
Source: https://developers.vidbeo.com/video-api/v2/reference/services/fetch-service

get /services/{service_id}
Get a service's details



# Fetch service params
Source: https://developers.vidbeo.com/video-api/v2/reference/services/fetch-service-params

get /services/{service_id}/params
Get any custom params



# Get TikTok creator
Source: https://developers.vidbeo.com/video-api/v2/reference/services/get-tiktok-creator

post /services/{service_id}/provider/tiktok/get-creator-info
Get info about a TikTok creator



# List services
Source: https://developers.vidbeo.com/video-api/v2/reference/services/list-services

get /services
Fetch all services



# Share video
Source: https://developers.vidbeo.com/video-api/v2/reference/services/share-video

post /services/{service_id}/provider/{service_provider}/upload/{video_id}
Share a video



# Update service
Source: https://developers.vidbeo.com/video-api/v2/reference/services/update-service

patch /services/{service_id}
Update a service's details



# Create session
Source: https://developers.vidbeo.com/video-api/v2/reference/sessions/create-session

post /sessions
Create a new session for the dashboard



# Delete session
Source: https://developers.vidbeo.com/video-api/v2/reference/sessions/delete-session

delete /sessions/{session_id}
Delete a session



# List sessions
Source: https://developers.vidbeo.com/video-api/v2/reference/sessions/list-sessions

get /sessions
Fetch all sessions for the authenticated user



# Fetch stream key
Source: https://developers.vidbeo.com/video-api/v2/reference/stream-keys/fetch-stream-key

get /stream_keys/{stream_key_id}
Get a stream key's details



# List stream keys
Source: https://developers.vidbeo.com/video-api/v2/reference/stream-keys/list-stream-keys

get /stream_keys
Fetch all stream keys



# Update stream key
Source: https://developers.vidbeo.com/video-api/v2/reference/stream-keys/update-stream-key

patch /stream_keys/{stream_key_id}
Update a stream key's details



# Create token
Source: https://developers.vidbeo.com/video-api/v2/reference/tokens/create-token

post /tokens
Create a new token



# Delete token
Source: https://developers.vidbeo.com/video-api/v2/reference/tokens/delete-token

delete /tokens/{token_id}
Delete a token



# Fetch token
Source: https://developers.vidbeo.com/video-api/v2/reference/tokens/fetch-token

get /tokens/{token_id}
Get a token's details



# List tokens
Source: https://developers.vidbeo.com/video-api/v2/reference/tokens/list-tokens

get /tokens
Fetch all tokens



# Update token
Source: https://developers.vidbeo.com/video-api/v2/reference/tokens/update-token

patch /tokens/{token_id}
Update a token's details



# List transcoders
Source: https://developers.vidbeo.com/video-api/v2/reference/transcoders/list-transcoders

get /transcoders
Fetch all transcoders



# Create transcribe
Source: https://developers.vidbeo.com/video-api/v2/reference/transcribes/create-transcribe

post /transcribes
Create a new transcribe



# Create trial
Source: https://developers.vidbeo.com/video-api/v2/reference/trials/create-trial

post /trials
Create a new account



# Create upload
Source: https://developers.vidbeo.com/video-api/v2/reference/uploads/create-upload

post /uploads
Create a new upload



# Delete upload
Source: https://developers.vidbeo.com/video-api/v2/reference/uploads/delete-upload

delete /uploads/{upload_id}
Delete an upload



# Fetch upload
Source: https://developers.vidbeo.com/video-api/v2/reference/uploads/fetch-upload

get /uploads/{upload_id}
Get an upload's details



# List uploads
Source: https://developers.vidbeo.com/video-api/v2/reference/uploads/list-uploads

get /uploads
Fetch all uploads



# Fetch usage delivered
Source: https://developers.vidbeo.com/video-api/v2/reference/usage/fetch-usage-delivered

get /usage_delivered
Fetch usage



# Fetch usage stored
Source: https://developers.vidbeo.com/video-api/v2/reference/usage/fetch-usage-stored

get /usage_stored
Fetch usage



# Delete user
Source: https://developers.vidbeo.com/video-api/v2/reference/users/delete-user

delete /users/{user_id}
Delete a user



# Enable MFA
Source: https://developers.vidbeo.com/video-api/v2/reference/users/enable-mfa

patch /users/{user_id}/mfa
Generate a QR code



# Fetch user
Source: https://developers.vidbeo.com/video-api/v2/reference/users/fetch-user

get /users/{user_id}
Get a user's details



# List users
Source: https://developers.vidbeo.com/video-api/v2/reference/users/list-users

get /users
Fetch all users



# Setup MFA
Source: https://developers.vidbeo.com/video-api/v2/reference/users/setup-mfa

patch /users/{user_id}/mfa/confirm
Confirm the authenticator app is setup by providing a valid six-digit code



# Update user
Source: https://developers.vidbeo.com/video-api/v2/reference/users/update-user

patch /users/{user_id}
Update a user's details



# Create card
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-card

post /videos/{video_id}/cards
Create a new card



# Create chapter
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-chapter

post /videos/{video_id}/chapters
Create a new chapter



# Create gate
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-gate

post /videos/{video_id}/gates
Create a new gate



# Create hotspot
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-hotspot

post /videos/{video_id}/hotspots
Create a new hotspot



# Create track
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-track

post /videos/{video_id}/tracks
Create a new track



# Create video
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/create-video

post /videos
Create a new video



# Delete card
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-card

delete /videos/{video_id}/cards/{card_id}
Delete a card



# Delete chapter
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-chapter

delete /videos/{video_id}/chapters/{chapter_id}
Delete a chapter



# Delete gate
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-gate

delete /videos/{video_id}/gates/{gate_id}
Delete a gate



# Delete hotspot
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-hotspot

delete /videos/{video_id}/hotspots/{hotspot_id}
Delete a hotspot



# Delete track
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-track

delete /videos/{video_id}/tracks/{track_id}
Delete a track



# Delete video
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/delete-video

delete /videos/{video_id}
Delete a video



# Fetch video
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/fetch-video

get /videos/{video_id}
Get a video's details



# List videos
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/list-videos

get /videos
Fetch all videos



# Replace thumbnail
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/replace-thumbnail

post /videos/{video_id}/thumbnail
Replace the video's thumbnail



# Update card
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/update-card

patch /videos/{video_id}/cards/{card_id}
Update a card's details



# Update chapter
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/update-chapter

patch /videos/{video_id}/chapters/{chapter_id}
Update a chapter's details



# Update gate
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/update-gate

patch /videos/{video_id}/gates/{gate_id}
Update a gate's details



# Update hotspot
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/update-hotspot

patch /videos/{video_id}/hotspots/{hotspot_id}
Update a hotspot's details



# Update video
Source: https://developers.vidbeo.com/video-api/v2/reference/videos/update-video

patch /videos/{video_id}
Update a video's details