openapi.city
Sign in

api.video

Video hosting and live streaming API

docs.api.video ↗
Version
1
OpenAPI
3.0.0
Endpoints
48
Schemas
77
91
Quality
Updated
3 days ago
Video video streaming hosting
Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://ws.api.video
https://sandbox.api.video

Endpoints

GET POST PUT PATCH DELETE

Advancedauthentication 2 endpoints

POST /auth/api-key

Returns a bearer token that can be used to authenticate other endpoint.

You can find the tutorial on using the disposable bearer token here.

operationId: AdvancedAuthentication_getBearerToken

Request Body

required
application/json
schema authenticate-payload
Property Type Required
apiKey string required

Responses

200

Success
400

Bad Request
POST /auth/api-key
POST /auth/refresh

Accepts the old bearer token and returns a new bearer token that can be used to authenticate other endpoint.

You can find the tutorial on using the disposable bearer token here.

operationId: AdvancedAuthentication_refreshBearerToken

Request Body

required
application/json
schema refresh-token-payload
Property Type Required
refreshToken string required

Responses

200

Success
400

Bad Request
POST /auth/refresh

Analytics 2 endpoints

GET /analytics/live-streams/plays

Retrieve filtered analytics about the number of plays for your live streams in a project.

operationId: Analytics_getLiveStreamPlays

Parameters

Name In Required Type Description
from query required string

Use this query parameter to set the start date for the time period that you want analytics for.

  • The API returns analytics data including the day you set in from.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
to query optional string

Use this optional query parameter to set the end date for the time period that you want analytics for.

  • If you do not specify a to date, the API returns analytics data starting from the from date up until today, and excluding today.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
dimension query required string

Use this query parameter to define the dimension that you want analytics for.

  • liveStreamId: Returns analytics based on the public live stream identifiers.
  • emittedAt: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in from and to is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals.
  • country: Returns analytics based on the viewers’ country. The list of supported country names are based on the GeoNames public database.
  • deviceType: Returns analytics based on the type of device used by the viewers during the play event. Possible response values are: computer, phone, tablet, tv, console, wearable, unknown.
  • operatingSystem: Returns analytics based on the operating system used by the viewers during the play event. Response values include windows, mac osx, android, ios, linux.
  • browser: Returns analytics based on the browser used by the viewers during the play event. Response values include chrome, firefox, edge, opera.
filter query optional string

Use this query parameter to filter your results to a specific live stream in a project that you want analytics for. You must use the liveStreamId: prefix when specifying a live stream ID.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
400

Bad request error
403

Forbidden - Disabled Analytics
404

Not Found
GET /analytics/live-streams/plays
GET /analytics/videos/plays

Retrieve filtered analytics about the number of plays for your videos in a project.

operationId: Analytics_getVideoPlays

Parameters

Name In Required Type Description
from query required string

Use this query parameter to set the start date for the time period that you want analytics for.

  • The API returns analytics data including the day you set in from.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
to query optional string

Use this optional query parameter to set the end date for the time period that you want analytics for.

  • If you do not specify a to date, the API returns analytics data starting from the from date up until today, and excluding today.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
dimension query required string

Use this query parameter to define the dimension that you want analytics for.

  • videoId: Returns analytics based on the public video identifiers.
  • emittedAt: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in from and to is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals.
  • country: Returns analytics based on the viewers’ country. The list of supported country names are based on the GeoNames public database.
  • deviceType: Returns analytics based on the type of device used by the viewers during the play event. Possible response values are: computer, phone, tablet, tv, console, wearable, unknown.
  • operatingSystem: Returns analytics based on the operating system used by the viewers during the play event. Response values include windows, mac osx, android, ios, linux.
  • browser: Returns analytics based on the browser used by the viewers during the play event. Response values include chrome, firefox, edge, opera.
filter query optional string

Use this query parameter to filter your results to a specific video in a project that you want analytics for. You must use the videoId: prefix when specifying a video ID.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
400

Bad request error
403

Forbidden - Disabled Analytics
404

Not Found
GET /analytics/videos/plays

Captions 5 endpoints

GET /videos/{videoId}/captions

Retrieve a list of available captions by video id.

operationId: Captions_listByVideoId

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to retrieve a list of captions for.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
404

Not Found
GET /videos/{videoId}/captions
DELETE /videos/{videoId}/captions/{language}

Delete a caption in a specific language by by video id.

operationId: Captions_deleteByLanguage

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to delete a caption from.
language path required string

A valid language identifier using IETF language tags. You can use primary subtags like en (English), extended subtags like fr-CA (French, Canada), or region subtags like zh-Hans-CN (Simplified Chinese used in the PRC).

  • This parameter only accepts dashes for separators, for example fr-CA. If you use a different separator in your request, the API returns an error.
  • When the value in your request does not match any covered language, the API returns an error.
  • You can find the list of supported tags here.

Responses

204

No Content
400

Bad request error
404

Not Found
DELETE /videos/{videoId}/captions/{language}
GET /videos/{videoId}/captions/{language}

Retrieve a caption for a video in a specific language.

operationId: Captions_getByLanguage

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want captions for.
language path required string

A valid language identifier using IETF language tags. You can use primary subtags like en (English), extended subtags like fr-CA (French, Canada), or region subtags like zh-Hans-CN (Simplified Chinese used in the PRC).

  • This parameter only accepts dashes for separators, for example fr-CA. If you use a different separator in your request, the API returns an error.
  • When the value in your request does not match any covered language, the API returns an error.
  • You can find the list of supported tags here.

Responses

200

Success
400

Bad request error
404

Not Found
GET /videos/{videoId}/captions/{language}
PATCH /videos/{videoId}/captions/{language}

Update caption settings.

operationId: Captions_updateSettings

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to have automatic captions for.
language path required string

A valid language identifier using IETF language tags. You can use primary subtags like en (English), extended subtags like fr-CA (French, Canada), or region subtags like zh-Hans-CN (Simplified Chinese used in the PRC).

  • This parameter only accepts dashes for separators, for example fr-CA. If you use a different separator in your request, the API returns an error.
  • When the value in your request does not match any covered language, the API returns an error.
  • You can find the list of supported tags here.

Request Body

required
application/json
schema captions-update-payload
Property Type Required
default boolean optional

Responses

200

Success
400

Bad request error
404

Not Found
PATCH /videos/{videoId}/captions/{language}
POST /videos/{videoId}/captions/{language}

Upload a VTT file to add captions to your video. More information can be found here

operationId: Captions_uploadVttFile

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to add a caption to.
language path required string

A valid language identifier using IETF language tags. You can use primary subtags like en (English), extended subtags like fr-CA (French, Canada), or region subtags like zh-Hans-CN (Simplified Chinese used in the PRC).

  • This parameter only accepts dashes for separators, for example fr-CA. If you use a different separator in your request, the API returns an error.
  • When the value in your request does not match any covered language, the API returns an error.
  • You can find the list of supported tags here.

Request Body

required
multipart/form-data
schema captions-upload-payload
Property Type Required
file string required

Responses

200

Success
400

Bad request error
404

Not Found
POST /videos/{videoId}/captions/{language}

Chapters 4 endpoints

GET /videos/{videoId}/chapters

Retrieve a list of all chapters for by video id.

operationId: Chapters_listByVideo

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to retrieve a list of chapters for.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
404

Not Found
GET /videos/{videoId}/chapters
DELETE /videos/{videoId}/chapters/{language}

Delete a chapter in a specific language by providing the video ID for the video you want to delete the chapter from and the language the chapter is in.

operationId: Chapters_deleteChapterInLanguage

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to delete a chapter from.
language path required string

A valid BCP 47 language representation.

Responses

204

No Content
404

Not Found
DELETE /videos/{videoId}/chapters/{language}
GET /videos/{videoId}/chapters/{language}

Retrieve a chapter for by video id in a specific language.

operationId: Chapters_getChapterByLanguage

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to show a chapter for.
language path required string

A valid BCP 47 language representation.

Responses

200

Success
404

Not Found
GET /videos/{videoId}/chapters/{language}
POST /videos/{videoId}/chapters/{language}

Upload a VTT file to add chapters to your video.
Chapters help break the video into sections. Read our tutorial for more details.

operationId: Chapters_uploadVttFile

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want to upload a chapter for.
language path required string

A valid BCP 47 language representation.

Request Body

required
multipart/form-data
schema chapters-update-payload
Property Type Required
file string required

Responses

200

Success
400

Bad Request
404

Not Found
POST /videos/{videoId}/chapters/{language}

Livestreams 7 endpoints

GET /live-streams

Get the list of livestreams on the workspace.

operationId: LiveStreams_listAll

Parameters

Name In Required Type Description
streamKey query optional string

The unique stream key that allows you to stream videos.
name query optional string

You can filter live streams by their name or a part of their name.
sortBy query optional string

Enables you to sort live stream results. Allowed attributes: name, createdAt, updatedAt.
name - the name of the live stream.
createdAt - the time a live stream was created.
updatedAt - the time a live stream was last updated.

When using createdAt or updatedAt, the API sorts the results based on the ISO-8601 time format.
sortOrder query optional string

Allowed: asc, desc. Ascending for date and time means that earlier values precede later ones. Descending means that later values preced earlier ones. For title, it is 0-9 and A-Z ascending and Z-A, 9-0 descending.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
GET /live-streams
POST /live-streams

Creates a livestream object.

operationId: LiveStreams_createLivestreamObject

Request Body

required
application/json
schema live-stream-creation-payload
Property Type Required
name string required
public boolean optional
playerId string optional
restreams array optional
└ name string required
└ serverUrl string required
└ streamKey string required

Responses

200

Success
400

Bad Request
POST /live-streams
DELETE /live-streams/{liveStreamId}

If you do not need a live stream any longer, you can send a request to delete it. All you need is the liveStreamId.

operationId: LiveStreams_deleteLivestream

Parameters

Name In Required Type Description
liveStreamId path required string

The unique ID for the live stream that you want to remove.

Responses

204

No Content
DELETE /live-streams/{liveStreamId}
GET /live-streams/{liveStreamId}

Get a livestream by id.

operationId: LiveStreams_getLivestreamById

Parameters

Name In Required Type Description
liveStreamId path required string

The unique ID for the live stream you want to watch.

Responses

200

Success
GET /live-streams/{liveStreamId}
PATCH /live-streams/{liveStreamId}

Updates the livestream object.

operationId: LiveStreams_updateLivestreamObject

Parameters

Name In Required Type Description
liveStreamId path required string

The unique ID for the live stream that you want to update information for such as player details.

Request Body

required
application/json
schema live-stream-update-payload
Property Type Required
name string optional
public boolean optional
playerId string optional
restreams array optional
└ name string required
└ serverUrl string required
└ streamKey string required

Responses

200

Success
400

Bad Request
PATCH /live-streams/{liveStreamId}
DELETE /live-streams/{liveStreamId}/thumbnail

Send the unique identifier for a live stream to delete its thumbnail.

operationId: LiveStreams_deleteThumbnail

Parameters

Name In Required Type Description
liveStreamId path required string

The unique identifier of the live stream whose thumbnail you want to delete.

Responses

200

Success
404

Not Found
DELETE /live-streams/{liveStreamId}/thumbnail
POST /live-streams/{liveStreamId}/thumbnail

Upload the thumbnail for the livestream.

operationId: LiveStreams_uploadThumbnail

Parameters

Name In Required Type Description
liveStreamId path required string

The unique ID for the live stream you want to upload.

Request Body

required
multipart/form-data
schema live-stream-thumbnail-upload-payload
Property Type Required
file string required

Responses

201

Created
400

Bad Request
404

Not Found
POST /live-streams/{liveStreamId}/thumbnail

Playerthemes 7 endpoints

GET /players

Retrieve a list of all the player themes you created, as well as details about each one.

operationId: GET_players

Parameters

Name In Required Type Description
sortBy query optional string

createdAt is the time the player was created. updatedAt is the time the player was last updated. The time is presented in ISO-8601 format.
sortOrder query optional string

Allowed: asc, desc. Ascending for date and time means that earlier values precede later ones. Descending means that later values preced earlier ones.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
400

Bad Request
GET /players
POST /players

Create a player for your video, and customise it.

operationId: POST_players

Request Body

required
application/json
schema player-theme-creation-payload
Property Type Required
link string optional
name string optional
text string optional
enableApi boolean optional
forceLoop boolean optional
hideTitle boolean optional
linkHover string optional
linkActive string optional
trackPlayed string optional
backgroundTop string optional
forceAutoplay boolean optional
trackUnplayed string optional
backgroundText string optional
enableControls boolean optional
trackBackground string optional
backgroundBottom string optional

Responses

201

Created
POST /players
DELETE /players/{playerId}

Delete a player if you no longer need it. You can delete any player that you have the player ID for.

operationId: PlayerThemes_deletePlayer

Parameters

Name In Required Type Description
playerId path required string

The unique identifier for the player you want to delete.

Responses

204

No Content
404

Not Found
DELETE /players/{playerId}
GET /players/{playerId}

Retreive a player theme by player id.

operationId: PlayerThemes_getThemeByPlayerId

Parameters

Name In Required Type Description
playerId path required string

The unique identifier for the player you want to retrieve.

Responses

200

Success
404

Not Found
GET /players/{playerId}
PATCH /players/{playerId}

Use a player ID to update specific details for a player.
NOTE: It may take up to 10 min before the new player configuration is available from our CDN.

operationId: PlayerThemes_updatePlayerDetails

Parameters

Name In Required Type Description
playerId path required string

The unique identifier for the player.

Request Body

required
application/json
schema player-theme-update-payload
Property Type Required
link string optional
name string optional
text string optional
enableApi boolean optional
forceLoop boolean optional
hideTitle boolean optional
linkHover string optional
linkActive string optional
trackPlayed string optional
backgroundTop string optional
forceAutoplay boolean optional
trackUnplayed string optional
backgroundText string optional
enableControls boolean optional
trackBackground string optional
backgroundBottom string optional

Responses

200

Success
404

Not Found
PATCH /players/{playerId}
DELETE /players/{playerId}/logo

Delete the logo associated to a player.

operationId: PlayerThemes_removeLogo

Parameters

Name In Required Type Description
playerId path required string

The unique identifier for the player.

Responses

204

No Content
404

Not Found
DELETE /players/{playerId}/logo
POST /players/{playerId}/logo

Upload an image file as a logo for your player. The image should fit within these constraints:

  • The image mime type must be image/jpeg or image/png. api.video recommends using png images with transparent background.
  • The image size should be a maximum of 200px width x 100px.
  • The file size should be a maximum of 100 KiB.
operationId: PlayerThemes_uploadLogo

Parameters

Name In Required Type Description
playerId path required string

The unique identifier for the player.

Request Body

required
multipart/form-data
schema player-theme-upload-logo-payload
Property Type Required
file string required
link string optional

Responses

201

Created
400

Bad Request
404

Not Found
POST /players/{playerId}/logo

Uploadtokens 4 endpoints

GET /upload-tokens

Retrieve a list of all currently active delegated tokens.

operationId: UploadTokens_listActiveDelegatedTokens

Parameters

Name In Required Type Description
sortBy query optional string

Allowed: createdAt, ttl. You can use these to sort by when a token was created, or how much longer the token will be active (ttl - time to live). Date and time is presented in ISO-8601 format.
sortOrder query optional string

Allowed: asc, desc. Ascending is 0-9 or A-Z. Descending is 9-0 or Z-A.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
GET /upload-tokens
POST /upload-tokens

Generates an upload token that can be used to replace the API Key. More information can be found here

operationId: UploadTokens_generateToken

Request Body

required
application/json
schema token-creation-payload
Property Type Required
ttl integer optional

Responses

200

Success
400

Bad Request
POST /upload-tokens
DELETE /upload-tokens/{uploadToken}

Delete an existing upload token. This is especially useful for tokens you may have created that do not expire.

operationId: UploadTokens_deleteToken

Parameters

Name In Required Type Description
uploadToken path required string

The unique identifier for the upload token you want to delete. Deleting a token will make it so the token can no longer be used for authentication.

Responses

204

No Content
404

Not Found
DELETE /upload-tokens/{uploadToken}
GET /upload-tokens/{uploadToken}

Retrieve details about a specific upload token by id.

operationId: UploadTokens_getDetails

Parameters

Name In Required Type Description
uploadToken path required string

The unique identifier for the token you want information about.

Responses

200

Success
404

Not Found
GET /upload-tokens/{uploadToken}

Videos 10 endpoints

POST /upload

Uploading a video with the delegated upload token.

operationId: POST_upload

Parameters

Name In Required Type Description
token query required string

The unique identifier for the token you want to use to upload a video.
Content-Range header optional string

Content-Range represents the range of bytes that will be returned as a result of the request. Byte ranges are inclusive, meaning that bytes 0-999 represents the first 1000 bytes in a file or object.

Request Body

required
multipart/form-data
schema token-upload-payload
Property Type Required
file string required
videoId string optional

Responses

201

Created
400

Bad Request
POST /upload
GET /videos

List all the video objects that are associated with the current workspace.

operationId: Videos_listAllObjects

Parameters

Name In Required Type Description
title query optional string

The title of a specific video you want to find. The search will match exactly to what term you provide and return any videos that contain the same term as part of their titles.
tags[] query optional array

A tag is a category you create and apply to videos. You can search for videos with particular tags by listing one or more here. Only videos that have all the tags you list will be returned.
metadata query optional object

Videos can be tagged with metadata tags in key:value pairs. You can search for videos with specific key value pairs using this parameter. Dynamic Metadata allows you to define a key that allows any value pair.
description query optional string

Retrieve video objects by description.
liveStreamId query optional string

Retrieve video objects that were recorded from a live stream by liveStreamId.
sortBy query optional string

Use this parameter to sort videos by the their created time, published time, updated time, or by title.
sortOrder query optional string

Use this parameter to sort results. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
400

Bad Request
GET /videos
POST /videos

Creates a video object. More information on video objects can be found here.

operationId: Videos_createObject

Request Body

required

video to create

application/json
schema video-creation-payload
Property Type Required
clip object optional
└ endTimecode string optional
└ startTimecode string optional
tags array optional
title string required
public boolean optional
source string optional
metadata array optional
└ key string optional
└ value string optional
playerId string optional
panoramic boolean optional
watermark object optional
└ id string optional
└ top string optional
└ left string optional
└ right string optional
└ width string optional
└ bottom string optional
└ height string optional
└ opacity string optional
mp4Support boolean optional
description string optional

Responses

201

Created
202

Accepted
400

Bad Request
POST /videos
DELETE /videos/{videoId}

Delete a video object by video ID.

operationId: Videos_deleteVideoObject

Parameters

Name In Required Type Description
videoId path required string

The video ID for the video you want to delete.

Responses

204

No Content
404

Not Found
DELETE /videos/{videoId}
GET /videos/{videoId}

Retrieve the video details by video id.

operationId: Videos_getVideoObject

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want details about.

Responses

200

Success
404

Not Found
GET /videos/{videoId}
PATCH /videos/{videoId}

Update the parameters associated with a video ID.

operationId: Videos_updateVideoObjectParameters

Parameters

Name In Required Type Description
videoId path required string

The video ID for the video you want to update.

Request Body

required
application/json
schema video-update-payload
Property Type Required
tags array optional
title string optional
public boolean optional
metadata array optional
└ key string optional
└ value string optional
playerId string optional
panoramic boolean optional
mp4Support boolean optional
description string optional

Responses

200

Success
400

Bad Request
404

Not Found
PATCH /videos/{videoId}
POST /videos/{videoId}/source

Ingest a video from a source or file.

operationId: Videos_ingestVideoFromSource

Parameters

Name In Required Type Description
videoId path required string

Enter the videoId you want to use to upload your video.
Content-Range header optional string

part <part>/<total_parts> ; bytes <from_byte>-<to_byte>/<total_bytes>

Request Body

required
multipart/form-data
schema video-upload-payload
Property Type Required
file string required

Responses

201

Created
400

Bad Request
404

Not Found
POST /videos/{videoId}/source
GET /videos/{videoId}/status

Retrieve upload status and encoding status to determine when the video is uploaded or ready to playback. Once encoding is completed, the response also lists the available stream qualities.

operationId: Videos_getVideoStatusAndDetails

Parameters

Name In Required Type Description
videoId path required string

The unique identifier for the video you want the status for.

Responses

200

Success
404

Not Found
GET /videos/{videoId}/status
PATCH /videos/{videoId}/thumbnail

Set a thumbnail from a specific time interval within a video.

operationId: Videos_setThumbnailFromInterval

Parameters

Name In Required Type Description
videoId path required string

Unique identifier of the video you want to add a thumbnail to, where you use a section of your video as the thumbnail.

Request Body

required
application/json
schema video-thumbnail-pick-payload
Property Type Required
timecode string required

Responses

200

Success
404

Not Found
PATCH /videos/{videoId}/thumbnail
POST /videos/{videoId}/thumbnail

Upload a thumbnail for a certain video.

operationId: Videos_uploadThumbnail

Parameters

Name In Required Type Description
videoId path required string

Unique identifier of the chosen video

Request Body

required
multipart/form-data
schema video-thumbnail-upload-payload
Property Type Required
file string required

Responses

200

Success
400

Bad Request
404

Not Found
POST /videos/{videoId}/thumbnail

Watermarks 3 endpoints

GET /watermarks

List all watermarks associated with your workspace.

operationId: Watermarks_listAll

Parameters

Name In Required Type Description
sortBy query optional string

Allowed: createdAt. You can search by the time watermark were created at.
sortOrder query optional string

Allowed: asc, desc. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
400

Bad Request
GET /watermarks
POST /watermarks

Create a new watermark by uploading a JPG or a PNG image.

operationId: POST_watermark

Request Body

required
multipart/form-data
schema watermark-upload-payload
Property Type Required
file string required

Responses

200

Success
400

Bad Request
POST /watermarks
DELETE /watermarks/{watermarkId}

Delete a watermark.

operationId: DELETE_watermark

Parameters

Name In Required Type Description
watermarkId path required string

The watermark ID for the watermark you want to delete.

Responses

204

No Content
404

Not Found
DELETE /watermarks/{watermarkId}

Webhooks 4 endpoints

GET /webhooks

Retrieve a list of all webhooks configured for the current workspace.

operationId: Webhooks_listAll

Parameters

Name In Required Type Description
events query optional string

The webhook event that you wish to filter on.
currentPage query optional integer

Choose the number of search results to return per page. Minimum value: 1
pageSize query optional integer

Results per page. Allowed values 1-100, default is 25.

Responses

200

Success
GET /webhooks
POST /webhooks

Webhooks can push notifications to your server, rather than polling api.video for changes. We currently offer four events:

  • video.encoding.quality.completed Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification. It will look like { "type": "video.encoding.quality.completed", "emittedAt": "2021-01-29T16:46:25.217+01:00", "videoId": "viXXXXXXXX", "encoding": "hls", "quality": "720p"}. This request says that the 720p HLS encoding was completed.
  • live-stream.broadcast.started When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
  • live-stream.broadcast.ended This event fires when a live stream has finished broadcasting.
  • video.source.recorded This event occurs when a live stream is recorded and submitted for encoding.
operationId: Webhooks_createWebhookEvent

Request Body

required
application/json
schema webhooks-creation-payload
Property Type Required
url string required
events array required

Responses

201

Created
400

Bad Request
POST /webhooks
DELETE /webhooks/{webhookId}

This endpoint will delete the indicated webhook.

operationId: Webhooks_deleteWebhook

Parameters

Name In Required Type Description
webhookId path required string

The webhook you wish to delete.

Responses

204

No Content
404

Not Found
DELETE /webhooks/{webhookId}
GET /webhooks/{webhookId}

Retrieve webhook details by id.

operationId: Webhooks_getDetailsById

Parameters

Name In Required Type Description
webhookId path required string

The unique webhook you wish to retreive details on.

Responses

200

Success
GET /webhooks/{webhookId}

Schemas

object 403-error-schema 
{
  "type": "object",
  "title": "403 Forbidden",
  "properties": {
    "name": {
      "type": "string",
      "nullable": true,
      "description": "The name of the parameter that caused the error."
    },
    "type": {
      "type": "string",
      "description": "A link to the error documentation."
    },
    "title": {
      "type": "string",
      "description": "A description of the error that occurred."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code."
    }
  }
}
object access-token 
{
  "type": "object",
  "title": "AccessToken",
  "example": {
    "expires_in": 3600,
    "token_type": "qui nulla l",
    "access_token": "est",
    "refresh_token": "cillum"
  },
  "properties": {
    "expires_in": {
      "type": "integer",
      "description": "Lists the time in seconds when your access token expires. It lasts for one hour."
    },
    "token_type": {
      "type": "string",
      "default": "bearer",
      "description": "The type of token you have."
    },
    "access_token": {
      "type": "string",
      "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjUyZWM4NWUyMjFkODZjOWI0NDQ5NzBhMjQwMzUyOWQ4MDQyNGQ3ZmJjYjFlYWM2MjVlM2VkMjI2YWRlNTcxMDY2NDUyZDc0NjdhN2E4NjI0In0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiNTJlYzg1ZTIyMWQ4NmM5YjQ0NDk3MGEyNDAzNTI5ZDgwNDI0ZDdmYmNiMWVhYzYyNWUzZWQyMjZhZGU1NzEwNjY0NTJkNzQ2N2E3YTg2MjQiLCJpYXQiOjE1MjUyNzYxNDcsIm5iZiI6MTUyNTI3NjE0NywiZXhwIjoxNTI1Mjc5NzQ3LCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.rUvishDNyJLNlI4W5VmguNecm5KD2uZgPkKJQbaqw-cJbSrVxkSbiKYtk_E3cz3WT7-IS2yFTsYN3uIo5Rbit8_HftweyEp2bdBRI8yjR6oZZ1sNJJXswISN1i2kk4r-aaxu7Xxf_LtsjOMUj_YZsvcc2nqBXPKjHbJCJryx3DDJaIcymOqao7nhQaCCQyrQooAXNTYs4E9fWN1dC_x2O-zok5TuG-xhEW-umwxfSUMWNgSTkz38ACceQ0PCJSgB3jqjDH4MwC7B3ppEPZuK5E6JhKeyRlalswRyYq3UQPnVeMTam7YQHsuTgbehF6WySW8i44o7V_MCe9hjPdp-WA",
      "description": "The access token containing security credentials allowing you to acccess the API. The token lasts for one hour."
    },
    "refresh_token": {
      "type": "string",
      "example": "def50200a28d88fb9aaa921be78eeb5604b071101a334899a7d5fc7492cf8ea752962ddc8961fe5c126101d4ecacd980396eb2fd494995b812dffcb98256c4277f790d1f658fc2d2e34f350740544e5232d69d68d34c648271d706c5e7049adac0b1832d0fdf71809715cc7e97fa63f65966deadb501a55ff469b0fd23a637cb6acbe9d9b8594a17f09efc2efeed82984764a0065d5e29c950c7b081a61ba2aaa192be3085c400ee37eac50fa9320ce2cfe8916c8165418d23e9f91b6a5c8515e1d74ee193a5a1ca01954fbff27361c20184240be2359e0afbed0bf1c762cf872450b5e8b5d4704f4fd9583e4470adc98409dd42965709712806bd9019378a72eea0b4912ce684ffd833db5806ab84174f905db2a75380071d004615c944bb8f8c4045cce7234c2be9a2330522cf7f067b8e58f57cffb6edb4b7ef91313e12bcde47e5e76ceee7fa52990132288f345d33ed917ae4fd54b7284f8964d898e97e1ee3bc4157f75d7fee63976e4be66ac1ec32ef74afa533f0eb593523f226cbec57d196ac8962",
      "description": "A token you can use to get the next access token when your current access token expires."
    }
  }
}
object additional-bad-request-errors 
{
  "type": "object",
  "title": "BadRequest",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the parameter that caused the error."
    },
    "type": {
      "type": "string",
      "description": "A link to the error documentation."
    },
    "title": {
      "type": "string",
      "description": "A description of the error that occurred."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code."
    }
  }
}
object analytics-data 
{
  "type": "object",
  "title": "Play event analytics data",
  "required": [
    "value",
    "plays"
  ],
  "properties": {
    "plays": {
      "type": "integer",
      "example": 100,
      "description": "Shows the number of play events for one specific `value`."
    },
    "value": {
      "type": "string",
      "example": "vi3q7HxhApxRF1c8F8r6VeaI",
      "description": "Shows a value for the property you have specified for `dimension` in your request. For example, if you requested `dimension=videoId`, each `value` field in the response returns a different videoId."
    }
  }
}
object analytics-plays-400-error 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the parameter that caused the error."
    },
    "type": {
      "type": "string",
      "description": "A link to the error documentation."
    },
    "title": {
      "type": "string",
      "description": "A description of the error that occurred."
    },
    "detail": {
      "type": "string",
      "description": "A solution for the error."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code."
    }
  }
}
object analytics-plays-response 
{
  "type": "object",
  "title": "Play event analytics response",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/analytics-data"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object authenticate-payload 
{
  "type": "object",
  "title": "ApiKey",
  "example": {
    "apiKey": "9VxMaPgsaFg7EBqmuspSzF7"
  },
  "required": [
    "apiKey"
  ],
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Your account API key. You can use your sandbox API key, or you can use your production API key."
    }
  }
}
object bad-request 
{
  "type": "object",
  "title": "BadRequest",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the parameter that caused the error."
    },
    "type": {
      "type": "string",
      "description": "A link to the error documentation."
    },
    "title": {
      "type": "string",
      "description": "A description of the error that occurred."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code."
    },
    "problems": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/additional-bad-request-errors"
      },
      "description": "Returns any additional problems in the request in an array of objects.",
      "uniqueItems": true
    }
  }
}
object bytes-range 
{
  "type": "object",
  "title": "BytesRange",
  "properties": {
    "to": {
      "type": "integer",
      "example": 9999,
      "description": "The ending point for the range of bytes for a chunk of a video."
    },
    "from": {
      "type": "integer",
      "example": 0,
      "description": "The starting point for the range of bytes for a chunk of a video."
    },
    "total": {
      "type": "integer",
      "example": 10000,
      "description": "The total number of expected bytes."
    }
  }
}
object caption 
{
  "type": "object",
  "title": "Caption",
  "properties": {
    "src": {
      "type": "string",
      "example": "https://cdn.api.video/vod/vi1111DinStg3oBbN79GklWS/captions/sr-Cyrl.vtt",
      "description": "A direct URL to the uploaded caption file."
    },
    "uri": {
      "type": "string",
      "example": "/videos/vi1111DinStg3oBbN79GklWS/captions/sr-Cyrl",
      "description": "The unique resource identifier of the uploaded caption."
    },
    "default": {
      "type": "boolean",
      "default": false,
      "example": false,
      "description": "Whether you will have subtitles or not. True for yes you will have subtitles, false for no you will not have subtitles."
    },
    "srclang": {
      "type": "string",
      "example": "sr-Cyrl",
      "description": "Indicates the language of the uploaded caption file using IETF language tags."
    },
    "languageName": {
      "type": "string",
      "example": "српски (ћирилица)",
      "description": "Returns the native name of the caption language in UTF-8 encoding."
    }
  }
}
object captions-list-response 
{
  "type": "object",
  "title": "VideoCaptions",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/caption"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object captions-update-payload 
{
  "type": "object",
  "title": "CaptionsUpdatePayload",
  "properties": {
    "default": {
      "type": "boolean"
    }
  }
}
object captions-upload-payload 
{
  "type": "object",
  "title": "CaptionsUploadPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The video text track (VTT) you want to upload."
    }
  }
}
object chapter 
{
  "type": "object",
  "title": "Chapter",
  "properties": {
    "src": {
      "type": "string",
      "example": "https://cdn.api.video/vod/vi3N6cDinStg3oBbN79GklWS/chapters/fr.vtt",
      "description": "The link to your VTT file, which contains your chapters information for the video."
    },
    "uri": {
      "type": "string"
    },
    "language": {
      "type": "string"
    }
  }
}
object chapters-list-response 
{
  "type": "object",
  "title": "VideoChapters",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/chapter"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object chapters-update-payload 
{
  "type": "object",
  "title": "ChaptersUpdatePayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The VTT file describing the chapters you want to upload."
    }
  }
}
object link 
{
  "type": "object",
  "properties": {
    "rel": {
      "type": "string"
    },
    "uri": {
      "type": "string"
    }
  }
}
object live-stream 
{
  "type": "object",
  "title": "LiveStream",
  "required": [
    "liveStreamId",
    "restreams"
  ],
  "properties": {
    "name": {
      "type": "string",
      "example": "My Live Stream",
      "description": "The name of your live stream."
    },
    "assets": {
      "$ref": "#/components/schemas/live-stream-assets"
    },
    "public": {
      "type": "boolean",
      "example": true,
      "description": "Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Learn more about the Private Video feature [here](https://docs.api.video/delivery-analytics/video-privacy-access-management)."
    },
    "playerId": {
      "type": "string",
      "example": "pl45d5vFFGrfdsdsd156dGhh",
      "description": "The unique identifier for the player."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2020-01-31T10:17:47+00:00",
      "description": "When the player was created, presented in ISO-8601 format."
    },
    "restreams": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/restreams-response-object"
      },
      "description": "Returns the list of RTMP restream destinations."
    },
    "streamKey": {
      "type": "string",
      "example": "dw-dew8-q6w9-k67w-1ws8",
      "description": "The unique, private stream key that you use to begin streaming."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2020-01-31T10:18:47+00:00",
      "description": "When the player was last updated, presented in ISO-8601 format."
    },
    "broadcasting": {
      "type": "boolean",
      "example": true,
      "description": "Whether or not you are broadcasting the live video you recorded for others to see. True means you are broadcasting to viewers, false means you are not."
    },
    "liveStreamId": {
      "type": "string",
      "example": "li400mYKSgQ6xs7taUeSaEKr",
      "description": "The unique identifier for the live stream. Live stream IDs begin with \"li.\""
    }
  }
}
object live-stream-assets 
{
  "type": "object",
  "title": "LiveStreamAssets",
  "properties": {
    "hls": {
      "type": "string",
      "format": "uri",
      "example": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
      "description": "The http live streaming (HLS) link for your live video stream."
    },
    "iframe": {
      "type": "string",
      "example": "<iframe src=\\\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\\\" width=\\\"100%\\\" height=\\\"100%\\\" frameborder=\\\"0\\\" scrolling=\\\"no\\\" allowfullscreen=\\\"\\\"></iframe>",
      "description": "The embed code for the iframe containing your live video stream."
    },
    "player": {
      "type": "string",
      "format": "uri",
      "example": "https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr",
      "description": "A link to the video player that is playing your live stream."
    },
    "thumbnail": {
      "type": "string",
      "format": "uri",
      "example": "https://live.api.video/li400mYKSgQ6xs7taUeSaEKr/thumbnail.jpg",
      "description": "A link to the thumbnail for your video."
    }
  }
}
object live-stream-creation-payload 
{
  "type": "object",
  "title": "LiveStreamCreationPayload",
  "example": {
    "name": "Test live",
    "playerId": "pl4f4ferf5erfr5zed4fsdd",
    "restreams": [
      {
        "name": "YouTube",
        "serverUrl": "rtmp://youtube.broadcast.example.com",
        "streamKey": "dw-dew8-q6w9-k67w-1ws8"
      },
      {
        "name": "Twitch",
        "serverUrl": "rtmp://twitch.broadcast.example.com",
        "streamKey": "dw-dew8-q6w9-k67w-1ws8"
      }
    ]
  },
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "example": "My Live Stream Video",
      "description": "Add a name for your live stream here."
    },
    "public": {
      "type": "boolean",
      "description": "Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Learn more about the Private Video feature [here](https://docs.api.video/delivery-analytics/video-privacy-access-management)."
    },
    "playerId": {
      "type": "string",
      "example": "pl4f4ferf5erfr5zed4fsdd",
      "description": "The unique identifier for the player."
    },
    "restreams": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/restreams-request-object"
      },
      "maxItems": 5,
      "description": "Use this parameter to add, edit, or remove RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations."
    }
  }
}
object live-stream-list-response 
{
  "type": "object",
  "title": "LiveStreams",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/live-stream"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object live-stream-session 
{
  "type": "object",
  "title": "LiveStreamSession",
  "properties": {
    "os": {
      "$ref": "#/components/schemas/video-session-os"
    },
    "client": {
      "$ref": "#/components/schemas/live-stream-session-client"
    },
    "device": {
      "$ref": "#/components/schemas/live-stream-session-device"
    },
    "session": {
      "$ref": "#/components/schemas/live-stream-session-session"
    },
    "location": {
      "$ref": "#/components/schemas/live-stream-session-location"
    },
    "referrer": {
      "$ref": "#/components/schemas/live-stream-session-referrer"
    }
  }
}
object live-stream-session-client 
{
  "type": "object",
  "title": "LiveStreamSessionClient",
  "properties": {
    "name": {
      "type": "string",
      "example": "Firefox",
      "description": "The name of the browser used to view the live stream session."
    },
    "type": {
      "type": "string",
      "example": "browser",
      "description": "The type of client used to view the live stream session."
    },
    "version": {
      "type": "string",
      "example": "67.0",
      "description": "The version of the browser used to view the live stream session."
    }
  },
  "description": "What kind of browser the viewer is using for the live stream session."
}
object live-stream-session-device 
{
  "type": "object",
  "title": "LiveStreamSessionDevice",
  "properties": {
    "type": {
      "type": "string",
      "example": "desktop",
      "description": "What the type is like desktop, laptop, mobile."
    },
    "model": {
      "type": "string",
      "example": "unknown",
      "description": "The specific model of the device, if known."
    },
    "vendor": {
      "type": "string",
      "example": "Dell",
      "description": "If known, what the brand of the device is, like Apple, Dell, etc."
    }
  },
  "description": "What type of device the user is on when in the live stream session."
}
object live-stream-session-location 
{
  "type": "object",
  "title": "LiveStreamSessionLocation",
  "properties": {
    "city": {
      "type": "string",
      "example": "Paris",
      "description": "The city of the viewer of the live stream."
    },
    "country": {
      "type": "string",
      "example": "France",
      "description": "The country of the viewer of the live stream."
    }
  },
  "description": "The location of the viewer of the live stream."
}
object live-stream-session-referrer 
{
  "type": "object",
  "title": "LiveStreamSessionReferrer",
  "properties": {
    "url": {
      "type": "string",
      "example": "https://api.video",
      "description": "The website the viewer of the live stream was referred to in order to view the live stream."
    },
    "medium": {
      "type": "string",
      "example": "organic",
      "description": "The type of search that brought the viewer to the live stream. Organic would be they found it on their own, paid would be they found it via an advertisement."
    },
    "source": {
      "type": "string",
      "example": "https://google.com",
      "description": "Where the viewer came from to see the live stream (usually where they searched from)."
    },
    "searchTerm": {
      "type": "string",
      "example": "video stream",
      "description": "What term they searched for that led them to the live stream."
    }
  }
}
object live-stream-session-session 
{
  "type": "object",
  "title": "LiveStreamSessionSession",
  "properties": {
    "endedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T12:45:01.109Z",
      "description": "When the session ended, with the date and time presented in ISO-8601 format."
    },
    "loadedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109Z",
      "description": "When the session started, with the date and time presented in ISO-8601 format."
    },
    "sessionId": {
      "type": "string",
      "description": "A unique identifier for your session. You can use this to track what happens during a specific session."
    }
  }
}
object live-stream-thumbnail-upload-payload 
{
  "type": "object",
  "title": "LiveStreamThumbnailUploadPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The image to be added as a thumbnail. The mime type should be image/jpeg, image/png or image/webp. The max allowed size is 8 MiB."
    }
  }
}
object live-stream-update-payload 
{
  "type": "object",
  "title": "LiveStreamUpdatePayload",
  "properties": {
    "name": {
      "type": "string",
      "example": "My Live Stream Video",
      "description": "The name you want to use for your live stream."
    },
    "public": {
      "type": "boolean",
      "description": "Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Learn more about the Private Video feature [here](https://docs.api.video/delivery-analytics/video-privacy-access-management)."
    },
    "playerId": {
      "type": "string",
      "example": "pl45KFKdlddgk654dspkze",
      "description": "The unique ID for the player associated with a live stream that you want to update."
    },
    "restreams": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/restreams-request-object"
      },
      "maxItems": 5,
      "description": "Use this parameter to add, edit, or remove RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations. This operation updates all restream destinations in the same request. If you do not want to modify an existing restream destination, you need to include it in your request, otherwise it is removed."
    }
  }
}
object metadata 
{
  "type": "object",
  "title": "Metadata",
  "properties": {
    "key": {
      "type": "string",
      "example": "Color",
      "description": "The constant that defines the data set."
    },
    "value": {
      "type": "string",
      "example": "Green",
      "description": "A variable which belongs to the data set."
    }
  },
  "x-client-all-args-constructor": true
}
object not-found 
{
  "type": "object",
  "title": "NotFound",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    }
  }
}
object pagination 
{
  "type": "object",
  "title": "Pagination",
  "example": {
    "links": {
      "last": {
        "rel": "last",
        "uri": "/videos/search?currentPage=6&pageSize=20"
      },
      "next": {
        "rel": "next",
        "uri": "/videos/search?currentPage=4&pageSize=20"
      },
      "first": {
        "rel": "first",
        "uri": "/videos/search?currentPage=1&pageSize=20"
      },
      "previous": {
        "rel": "previous",
        "uri": "/videos/search?currentPage=2&pageSize=20"
      }
    },
    "pageSize": 20,
    "itemsTotal": 123,
    "pagesTotal": 7,
    "currentPage": 3,
    "currentPageItems": 20
  },
  "required": [
    "links"
  ],
  "properties": {
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/pagination-link"
      }
    },
    "pageSize": {
      "type": "integer",
      "readOnly": true,
      "description": "Maximum number of item per page."
    },
    "itemsTotal": {
      "type": "integer",
      "readOnly": true,
      "description": "Total number of items that exist."
    },
    "pagesTotal": {
      "type": "integer",
      "readOnly": true,
      "description": "Number of items listed in the current page."
    },
    "currentPage": {
      "type": "integer",
      "readOnly": true,
      "description": "The current page index."
    },
    "currentPageItems": {
      "type": "integer",
      "readOnly": true,
      "description": "The number of items on the current page."
    }
  }
}
object pagination-link 
{
  "type": "object",
  "title": "PaginationLink",
  "properties": {
    "rel": {
      "type": "string"
    },
    "uri": {
      "type": "string",
      "format": "uri"
    }
  }
}
object player-session-event 
{
  "type": "object",
  "title": "PlayerSessionEvent",
  "properties": {
    "at": {
      "type": "integer"
    },
    "to": {
      "type": "integer"
    },
    "from": {
      "type": "integer"
    },
    "type": {
      "type": "string",
      "example": "play",
      "description": "Possible values are: ready, play, pause, resume, seek.backward, seek.forward, end"
    },
    "emittedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109Z",
      "description": "When an event occurred, presented in ISO-8601 format."
    }
  }
}
object player-theme 
{
  "type": "object",
  "title": "PlayerTheme",
  "required": [
    "playerId"
  ],
  "properties": {
    "link": {
      "type": "string",
      "description": "RGBA color for all controls. Default: rgba(255, 255, 255, 1)"
    },
    "name": {
      "type": "string",
      "description": "The name of the player theme"
    },
    "text": {
      "type": "string",
      "description": "RGBA color for timer text. Default: rgba(255, 255, 255, 1)"
    },
    "assets": {
      "type": "object",
      "properties": {
        "link": {
          "type": "string",
          "example": "path/to/my/logo/mylogo.jpg",
          "description": "The path to the file containing your logo."
        },
        "logo": {
          "type": "string",
          "example": "mylogo.jpg",
          "description": "The name of the file containing the logo you want to use."
        }
      }
    },
    "playerId": {
      "type": "string",
      "example": "pl45KFKdlddgk654dspkze"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2020-01-31T10:17:47+00:00",
      "description": "When the player was created, presented in ISO-8601 format."
    },
    "enableApi": {
      "type": "boolean",
      "description": "enable/disable player SDK access. Default: true"
    },
    "forceLoop": {
      "type": "boolean",
      "description": "enable/disable looping. Default: false"
    },
    "hideTitle": {
      "type": "boolean",
      "description": "enable/disable title. Default: false"
    },
    "linkHover": {
      "type": "string",
      "description": "RGBA color for all controls when hovered. Default: rgba(255, 255, 255, 1)"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2020-01-31T10:18:47+00:00",
      "description": "When the player was last updated, presented in ISO-8601 format."
    },
    "linkActive": {
      "type": "string",
      "description": "RGBA color for the play button when hovered."
    },
    "trackPlayed": {
      "type": "string",
      "description": "RGBA color playback bar: played content. Default: rgba(88, 131, 255, .95)"
    },
    "backgroundTop": {
      "type": "string",
      "description": "RGBA color: top 50% of background. Default: rgba(0, 0, 0, .7)"
    },
    "forceAutoplay": {
      "type": "boolean",
      "description": "enable/disable player autoplay. Default: false"
    },
    "trackUnplayed": {
      "type": "string",
      "description": "RGBA color playback bar: downloaded but unplayed (buffered) content. Default: rgba(255, 255, 255, .35)"
    },
    "backgroundText": {
      "type": "string",
      "description": "RGBA color for title text. Default: rgba(255, 255, 255, 1)"
    },
    "enableControls": {
      "type": "boolean",
      "description": "enable/disable player controls. Default: true"
    },
    "trackBackground": {
      "type": "string",
      "description": "RGBA color playback bar: background. Default: rgba(255, 255, 255, .2)"
    },
    "backgroundBottom": {
      "type": "string",
      "description": "RGBA color: bottom 50% of background. Default: rgba(0, 0, 0, .7)"
    }
  }
}
object player-theme-creation-payload 
{
  "type": "object",
  "title": "PlayerThemeCreationPayload",
  "example": {
    "link": "rgba(255, 0, 0, .95)",
    "name": "My nice theme",
    "text": "rgba(255, 255, 255, .95)",
    "assets": {
      "link": "https://api.video",
      "logo": "https://cdn.api.video/player/pl14Db6oMJRH6SRVoOwORacK/logo.png"
    },
    "language": "en",
    "enableApi": true,
    "forceLoop": false,
    "hideTitle": false,
    "linkHover": "rgba(255, 255, 255, .75)",
    "linkActive": "rgba(255, 0, 0, .75)",
    "shapeAspect": "flat",
    "shapeMargin": 10,
    "shapeRadius": 3,
    "trackPlayed": "rgba(255, 255, 255, .95)",
    "backgroundTop": "rgba(72, 4, 45, 1)",
    "forceAutoplay": false,
    "trackUnplayed": "rgba(255, 255, 255, .1)",
    "backgroundText": "rgba(255, 255, 255, .95)",
    "enableControls": true,
    "trackBackground": "rgba(0, 0, 0, 0)",
    "backgroundBottom": "rgba(94, 95, 89, 1)",
    "shapeBackgroundTop": "rgba(50, 50, 50, .7)",
    "shapeBackgroundBottom": "rgba(50, 50, 50, .8)"
  },
  "properties": {
    "link": {
      "type": "string",
      "description": "RGBA color for all controls. Default: rgba(255, 255, 255, 1)"
    },
    "name": {
      "type": "string",
      "maxLength": 100,
      "description": "Add a name for your player theme here."
    },
    "text": {
      "type": "string",
      "description": "RGBA color for timer text. Default: rgba(255, 255, 255, 1)"
    },
    "enableApi": {
      "type": "boolean",
      "default": true,
      "description": "enable/disable player SDK access. Default: true"
    },
    "forceLoop": {
      "type": "boolean",
      "default": false,
      "description": "enable/disable looping. Default: false"
    },
    "hideTitle": {
      "type": "boolean",
      "default": false,
      "description": "enable/disable title. Default: false"
    },
    "linkHover": {
      "type": "string",
      "description": "RGBA color for all controls when hovered. Default: rgba(255, 255, 255, 1)"
    },
    "linkActive": {
      "type": "string",
      "description": "RGBA color for the play button when hovered."
    },
    "trackPlayed": {
      "type": "string",
      "description": "RGBA color playback bar: played content. Default: rgba(88, 131, 255, .95)"
    },
    "backgroundTop": {
      "type": "string",
      "description": "RGBA color: top 50% of background. Default: rgba(0, 0, 0, .7)"
    },
    "forceAutoplay": {
      "type": "boolean",
      "default": false,
      "description": "enable/disable player autoplay. Default: false"
    },
    "trackUnplayed": {
      "type": "string",
      "description": "RGBA color playback bar: downloaded but unplayed (buffered) content. Default: rgba(255, 255, 255, .35)"
    },
    "backgroundText": {
      "type": "string",
      "description": "RGBA color for title text. Default: rgba(255, 255, 255, 1)"
    },
    "enableControls": {
      "type": "boolean",
      "default": true,
      "description": "enable/disable player controls. Default: true"
    },
    "trackBackground": {
      "type": "string",
      "description": "RGBA color playback bar: background. Default: rgba(255, 255, 255, .2)"
    },
    "backgroundBottom": {
      "type": "string",
      "description": "RGBA color: bottom 50% of background. Default: rgba(0, 0, 0, .7)"
    }
  }
}
object player-theme-update-payload 
{
  "type": "object",
  "title": "PlayerThemeUpdatePayload",
  "properties": {
    "link": {
      "type": "string",
      "description": "RGBA color for all controls. Default: rgba(255, 255, 255, 1)"
    },
    "name": {
      "type": "string",
      "maxLength": 100,
      "description": "Add a name for your player theme here."
    },
    "text": {
      "type": "string",
      "description": "RGBA color for timer text. Default: rgba(255, 255, 255, 1)"
    },
    "enableApi": {
      "type": "boolean",
      "description": "enable/disable player SDK access. Default: true"
    },
    "forceLoop": {
      "type": "boolean",
      "description": "enable/disable looping. Default: false"
    },
    "hideTitle": {
      "type": "boolean",
      "description": "enable/disable title. Default: false"
    },
    "linkHover": {
      "type": "string",
      "description": "RGBA color for all controls when hovered. Default: rgba(255, 255, 255, 1)"
    },
    "linkActive": {
      "type": "string",
      "description": "RGBA color for the play button when hovered."
    },
    "trackPlayed": {
      "type": "string",
      "description": "RGBA color playback bar: played content. Default: rgba(88, 131, 255, .95)"
    },
    "backgroundTop": {
      "type": "string",
      "description": "RGBA color: top 50% of background. Default: rgba(0, 0, 0, .7)"
    },
    "forceAutoplay": {
      "type": "boolean",
      "description": "enable/disable player autoplay. Default: false"
    },
    "trackUnplayed": {
      "type": "string",
      "description": "RGBA color playback bar: downloaded but unplayed (buffered) content. Default: rgba(255, 255, 255, .35)"
    },
    "backgroundText": {
      "type": "string",
      "description": "RGBA color for title text. Default: rgba(255, 255, 255, 1)"
    },
    "enableControls": {
      "type": "boolean",
      "description": "enable/disable player controls. Default: true"
    },
    "trackBackground": {
      "type": "string",
      "description": "RGBA color playback bar: background. Default: rgba(255, 255, 255, .2)"
    },
    "backgroundBottom": {
      "type": "string",
      "description": "RGBA color: bottom 50% of background. Default: rgba(0, 0, 0, .7)"
    }
  }
}
object player-theme-upload-logo-payload 
{
  "type": "object",
  "title": "PlayerThemeUploadLogoPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "example": "mylogo.jpg",
      "description": "The name of the file you want to use for your logo."
    },
    "link": {
      "type": "string",
      "format": "string",
      "example": "https://my-company.com",
      "description": "A public link that you want to advertise in your player. For example, you could add a link to your company. When a viewer clicks on your logo, they will be taken to this address."
    }
  }
}
object player-themes-list-response 
{
  "type": "object",
  "title": "PlayerThemes",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/player-theme"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object quality 
{
  "type": "object",
  "title": "Quality",
  "properties": {
    "type": {
      "enum": [
        "hls",
        "mp4"
      ],
      "type": "string",
      "example": "hls",
      "description": "The type of video (hls or mp4)."
    },
    "status": {
      "enum": [
        "waiting",
        "encoding",
        "encoded",
        "failed"
      ],
      "type": "string",
      "description": "The status of your video. Statuses include waiting - the video is waiting to be encoded. encoding - the video is in the process of being encoded. encoded - the video was successfully encoded. failed - the video failed to be encoded."
    },
    "quality": {
      "enum": [
        "240p",
        "360p",
        "480p",
        "720p",
        "1080p",
        "2160p"
      ],
      "type": "string",
      "example": "720p",
      "description": "The quality of the video you have, in pixels. Choices include 360p, 480p, 720p, 1080p, and 2160p."
    }
  }
}
object refresh-token-payload 
{
  "type": "object",
  "title": "RefreshToken",
  "example": {
    "refreshToken": "def502005346d9cc2bd79a7793ab5bdabfefcaabfbb8c253f14733f1262077e1a3f38c4751d6d20f590c3784e531a82adc11f05fc1949aa46d5575aaa99cb84b9334ba66ac773576b5d7a418937ae337de62811d086dd42ad1164b12f87d67be6ffea18f2d50be9b95697b21c4d3c4372849bdb2287259cb80541570e913691a08b2fa33c85885930de15cebea627fc09f0255562ab3d39d87d4ff8fc02b00e252afcd480421dec7de9d1411176bcf669c527762e22294b453bc9ea06e9fa8ba5b873feb2ee14ce0a6a6ddd4b78c580631e210e9b9387265dc2bec9478a66a09dcdce1c40d2f856689e9d81742c9628a0b87b359e0b218ea1f07427eef89f999e47af89792f598e05847bd008fddc32ee63f4a601ffb4cd2ad08977f1c854ec358238322c918f05aa5a41f8a171dee497218408abc8283473f6112aeed7310815416a0fa36c63667e0ed014fa40b8992891bf58bae400d901c01450101c88f4978938ad138adc19cfe5698d60fd82cb27c586f6a8f70f4393c7c9e579df8739d46d249fb76d7"
  },
  "required": [
    "refreshToken"
  ],
  "properties": {
    "refreshToken": {
      "type": "string",
      "description": "The refresh token is either the first refresh token you received when you authenticated with the auth/api-key endpoint, or it's the refresh token from the last time you used the auth/refresh endpoint. Place this in the body of your request to obtain a new access token (which is valid for an hour) and a new refresh token.\n"
    }
  }
}
object restreams-request-object 
{
  "type": "object",
  "title": "Restreams request object",
  "required": [
    "name",
    "serverUrl",
    "streamKey"
  ],
  "properties": {
    "name": {
      "type": "string",
      "example": "My RTMP server",
      "description": "Use this parameter to define a name for the restream destination."
    },
    "serverUrl": {
      "type": "string",
      "example": "rtmp://my.broadcast.example.com/app",
      "description": "Use this parameter to set the RTMP URL of the restream destination."
    },
    "streamKey": {
      "type": "string",
      "example": "dw-dew8-q6w9-k67w-1ws8",
      "description": "Use this parameter to provide the unique key of the live stream that you want to restream."
    }
  },
  "description": "Adding restream destinations is optional. However, if you set a restream destination, you must provide all attributes for each destination."
}
object restreams-response-object 
{
  "type": "object",
  "title": "Restreams response object",
  "properties": {
    "name": {
      "type": "string",
      "example": "My RTMP server",
      "description": "Returns the name of a restream destination."
    },
    "serverUrl": {
      "type": "string",
      "example": "rtmp://my.broadcast.example.com/app",
      "description": "Returns the RTMP URL of a restream destination."
    },
    "streamKey": {
      "type": "string",
      "example": "dw-dew8-q6w9-k67w-1ws8",
      "description": "Returns the unique key of the live stream that is set up for restreaming."
    }
  }
}
object token-creation-payload 
{
  "type": "object",
  "title": "TokenCreationPayload",
  "example": {
    "ttl": 3600
  },
  "properties": {
    "ttl": {
      "type": "integer",
      "default": 0,
      "maximum": 2147483647,
      "minimum": 0,
      "description": "Time in seconds that the token will be active. A value of 0 means that the token has no exipration date. The default is to have no expiration."
    }
  }
}
object token-list-response 
{
  "type": "object",
  "title": "UploadTokens",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/upload-token"
      },
      "title": "uploadToken"
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}
object token-upload-payload 
{
  "type": "object",
  "title": "tokenUploadPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "example": "path/to/video/video.mp4",
      "description": "The path to the video you want to upload.",
      "x-client-chunk-upload": "true"
    },
    "videoId": {
      "type": "string",
      "description": "The video id returned by the first call to this endpoint in a large video upload scenario.",
      "x-client-ignore": true,
      "x-client-copy-from-response": true
    }
  }
}
object upload-token 
{
  "type": "object",
  "title": "UploadToken",
  "properties": {
    "ttl": {
      "type": "integer",
      "maximum": 2147483647,
      "minimum": 0,
      "description": "Time-to-live - how long the upload token is valid for."
    },
    "token": {
      "type": "string",
      "example": "to1tcmSFHeYY5KzyhOqVKMKb",
      "description": "The unique identifier for the token you will use to authenticate an upload."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-12-16T08:25:51.000Z",
      "description": "When the token was created, displayed in ISO-8601 format."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-12-16T09:25:51.000Z",
      "nullable": true,
      "description": "When the token expires, displayed in ISO-8601 format."
    }
  }
}
object video 
{
  "type": "object",
  "title": "Video",
  "example": {
    "tags": [
      "maths",
      "string theory",
      "video"
    ],
    "title": "Maths video",
    "actions": [
      "video_delete",
      "video_download",
      "video_update"
    ],
    "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz",
    "metadata": [
      {
        "key": "Author",
        "value": "John Doe"
      },
      {
        "key": "Format",
        "value": "Tutorial"
      }
    ],
    "createdAt": "4251-03-03T12:52:03.085Z",
    "description": "An amazing video explaining the string theory",
    "publishedAt": "4665-07-14T23:36:18.598Z"
  },
  "required": [
    "videoId"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": "\"tags\": [\"maths\", \"string theory\", \"video\"]",
      "description": "One array of tags (each tag is a string) in order to categorize a video. Tags may include spaces. \n"
    },
    "title": {
      "type": "string",
      "example": "Maths video",
      "description": "The title of the video content.\n"
    },
    "assets": {
      "$ref": "#/components/schemas/video-assets"
    },
    "public": {
      "type": "boolean",
      "example": false,
      "description": "Defines if the content is publicly reachable or if a unique token is needed for each play session. Default is true. Tutorials on [private videos](https://api.video/blog/endpoints/private-videos/).\n"
    },
    "source": {
      "$ref": "#/components/schemas/video-source"
    },
    "videoId": {
      "type": "string",
      "example": "vi4k0jvEUuaTdRAEjQ4Prklg",
      "description": "The unique identifier of the video object."
    },
    "metadata": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/metadata"
      },
      "example": "[{\"key\":\"Author\", \"value\":\"John Doe\"}, {\"key\":\"Format\", \"value\":\"Tutorial\"}]",
      "description": "Metadata you can use to categorise and filter videos. Metadata is a list of dictionaries, where each dictionary represents a key value pair for categorising a video. [Dynamic Metadata](https://api.video/blog/endpoints/dynamic-metadata/) allows you to define a key that allows any value pair.\n"
    },
    "playerId": {
      "type": "string",
      "example": "pl45KFKdlddgk654dspkze",
      "description": "The id of the player that will be applied on the video.\n"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109+00",
      "description": "When a video was created, presented in ISO-8601 format."
    },
    "panoramic": {
      "type": "boolean",
      "example": false,
      "description": "Defines if video is panoramic.\n"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-12-16T08:15:51.000Z",
      "description": "The date and time the video was updated. Date and time are provided using ISO-8601 UTC format."
    },
    "mp4Support": {
      "type": "boolean",
      "example": true,
      "description": "This lets you know whether mp4 is supported. If enabled, an mp4 URL will be provided in the response for the video.\n"
    },
    "description": {
      "type": "string",
      "example": "An amazing video explaining string theory.",
      "description": "A description for the video content.\n"
    },
    "publishedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-12-16T08:25:51.000Z",
      "description": "The date and time the API created the video. Date and time are provided using ISO-8601 UTC format."
    }
  }
}
object video-assets 
{
  "type": "object",
  "title": "VideoAssets",
  "properties": {
    "hls": {
      "type": "string",
      "format": "uri",
      "description": "This is the manifest URL. For HTTP Live Streaming (HLS), when a HLS video stream is initiated, the first file to download is the manifest. This file has the extension M3U8, and provides the video player with information about the various bitrates available for streaming."
    },
    "mp4": {
      "type": "string",
      "format": "uri",
      "example": "https://cdn.api.video/vod/vi4k0jvEUuaTdRAEjQ4Jfrgz/token/8fd70443-d9f0-45d2-b01c-12c8cfc707c9/mp4/source.mp4",
      "description": "Available only if mp4Support is enabled. Raw mp4 url."
    },
    "iframe": {
      "type": "string",
      "example": "<iframe src=\"//embed.api.video/c188ed58-3403-46a2-b91b-44603d10b2c9?token=831a9bd9-9f50-464c-a369-8e9d914371ae\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
      "description": "Code to use video from a third party website"
    },
    "player": {
      "type": "string",
      "format": "uri",
      "example": "https://embed.api.video/1b9d6ae8-8f57-4b6d-8552-d636926b4f5f?token=831a9bd9-9f50-464c-a369-8e9d914371ae",
      "description": "Raw url of the player."
    },
    "thumbnail": {
      "type": "string",
      "format": "uri",
      "example": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg",
      "description": "Poster of the video."
    }
  },
  "description": "Collection of details about the video object that you can use to work with the video object."
}
object video-clip 
{
  "type": "object",
  "properties": {
    "endTimecode": {
      "type": "string",
      "example": "00:02:33",
      "pattern": "^(?:\\d{2,3}:[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3}|\\:\\d{1,2})?|\\d{1,7})$",
      "description": "The timestamp that defines the end of the video clip you want to create. The value must follow the `HH:MM:SS` format."
    },
    "startTimecode": {
      "type": "string",
      "example": "00:01:15",
      "pattern": "^(?:\\d{2,3}:[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3}|\\:\\d{1,2})?|\\d{1,7})$",
      "description": "The timestamp that defines the beginning of the video clip you want to create. The value must follow the `HH:MM:SS` format."
    }
  },
  "description": "Use this object to create a smaller clip from a video you upload. \n- You can only create video clips in the same request where you create the video container.\n- You cannot update the starting or ending timestamps of a video clip after you created the video container.\n- When you upload a video file into a container where you defined a starting and ending timestamp, the API trims the video according to those timestamps to create a clip."
}
Load more schemas

Versions

Version Endpoints Schemas Ingested Status
1 48 77 2026-05-11 current
1 48 77 2026-04-16