Skip to content
On this page

Players

Players control how your videos are presented when using our embed code (for example the colour of the buttons). Our default settings are fine for most users however you may like to customise how your content looks.

You can manage players by making the following requests:

GET /players

Example request

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

Example response

json
{
    "success": true,
    "result": [
      {
        "id": "abcde12345abcde12345a",
        "aspectratio": "16:9",
        "autoplay": false,
        "colour": "",
        "controls": true,
        "buttons": "",
        "dnt": false,
        "keyboard": true,
        "loop": false,
        "name": "Example player",
        "muted": false,
        "playsinline": true,
        "preload": true,
        "quality": "",
        "title": false,
        "track": "",
        "created_by": "abcde12345abcde12345a",
        "created_time": "2021-01-01T12:00:00.000Z",
        "updated_by": "abcde12345abcde12345a",
        "updated_time": "2021-01-01T12:00:00.000Z"
      },
      ...
    ],
    "links": {},
    "errors": []
}

Optional parameters

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""Used to get the next page of results: if applicable we return this as part of the links.next URL

GET /players/:id

Example request

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

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "aspectratio": "16:9",
    "autoplay": false,
    "colour": "",
    "controls": true,
    "buttons": "",
    "dnt": false,
    "keyboard": true,
    "loop": false,
    "name": "Example player",
    "muted": false,
    "playsinline": true,
    "preload": true,
    "quality": "",
    "title": false,
    "track": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

Response format

KeyTypeDescription
idStringThe unique identifier given to this player
aspectratioStringThe aspect ratio used. Currently we only support the most common 16:9 ratio
autoplayBooleanShould the player try to play on-load (many browsers block this, though setting muted as true can help)?
colourStringA colour as hex e.g "#ff0000". If not specified the player will use a neutral palette
controlsBooleanWhether controls should be shown. The default is true
buttonsStringThe default value of an empty string means all will be shown. However if you only want a subset of them, use a comma-separated string. Such as: "play,progress,fullscreen"
dntBooleanShould the player avoid sending any personally identifiable data in analytics
keyboardBooleanEnable keyboard controls? By default they are enabled
loopBooleanShould the video automatically loop and restart when it ends?
nameStringThe name of this player in case you have multiple ones
mutedBooleanShould the video be muted on-load (this is often used in conjunction with autoplay)
playsinlineBooleanOn mobile devices, should the video play inline (as opposed to immediately going fullscreen)
preloadBooleanOn desktop/laptop, should we buffer a small amount of video on-load to improve performance?
qualityStringWe try and pick the best quality based on the connection speed but you can force it using "highest" or "lowest"
titleBooleanShould the video's name (its title) be shown on-load?
trackStringIf captions/subtitles are available for a video, set the language of the one to show immediately on-load e.g "en"
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe date and time it was last modified

PATCH /players/:id

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

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"name":"New name"}' \
"https://api.vidbeo.com/v2/players/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "aspectratio": "16:9",
    "autoplay": false,
    "colour": "",
    "controls": true,
    "buttons": "",
    "dnt": false,
    "keyboard": true,
    "loop": false,
    "name": "New name",
    "muted": false,
    "playsinline": true,
    "preload": true,
    "quality": "",
    "title": false,
    "track": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

DELETE /players/:id

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/players/abcde12345abcde12345a"

Example response

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

POST /players

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "Example"}' \
"https://api.vidbeo.com/v2/players"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "aspectratio": "16:9",
    "autoplay": false,
    "colour": "",
    "controls": true,
    "buttons": "",
    "dnt": false,
    "keyboard": true,
    "loop": false,
    "name": "Example",
    "muted": false,
    "playsinline": true,
    "preload": true,
    "quality": "",
    "title": false,
    "track": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

Required parameters

You need to provide a name.

KeyTypeDescription
nameStringThe name of the player (1-50 characters)