api.video
  1. Videos
api.video
  • Account
    • Show account
      GET
  • Analytics
    • List live stream player sessions
      GET
    • List player session events
      GET
    • List video player sessions
      GET
  • Authentication
    • Authenticate
      POST
    • Refresh token
      POST
  • Live
    • List all live streams
      GET
    • Create live stream
      POST
    • Delete a live stream
      DELETE
    • Show live stream
      GET
    • Update a live stream
      PATCH
    • Delete a thumbnail
      DELETE
    • Upload a thumbnail
      POST
  • Players
    • List all players
      GET
    • Create a player
      POST
    • Delete a player
      DELETE
    • Show a player
      GET
    • Update a player
      PATCH
    • Delete logo
      DELETE
    • Upload a logo
      POST
  • Videos - Delegated upload
    • Upload with an upload token
    • List all active upload tokens.
    • Generate an upload token
    • Delete an upload token
    • Show upload token
  • Videos
    • List all videos
      GET
    • Create a video
      POST
    • Delete a video
      DELETE
    • Show a video
      GET
    • Update a video
      PATCH
    • Upload a video
      POST
    • Show video status
      GET
    • Pick a thumbnail
      PATCH
    • Upload a thumbnail
      POST
  • Captions
    • List video captions
    • Delete a caption
    • Show a caption
    • Update caption
    • Upload a caption
  • Chapters
    • List video chapters
    • Delete a chapter
    • Show a chapter
    • Upload a chapter
  • Webhooks
    • List all webhooks
    • Create Webhook
    • Delete a Webhook
    • Show Webhook details
  1. Videos

List all videos

GET
/videos
Videos
Requests to this endpoint return a list of your videos (with all their details). With no parameters added to this query, the API returns all videos. You can filter what videos the API returns using the parameters described below. We have several tutorials that demonstrate this endpoint.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET 'https://ws.api.video/videos'
Response Response Example
200 - response
{
  "data": [
    {
      "assets": {
        "hls": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/hls/manifest.m3u8",
        "iframe": "<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>",
        "mp4": "https://cdn.api.video/vod/vi4k0jvEUuaTdRAEjQ4Jfrgz/token/8fd70443-d9f0-45d2-b01c-12c8cfc707c9/mp4/720/source.mp4",
        "player": "https://embed.api.video/c188ed58-3403-46a2-b91b-44603d10b2c9?token=831a9bd9-9f50-464c-a369-8e9d914371ae",
        "thumbnail": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg"
      },
      "description": "An amazing video explaining the string theory",
      "metadata": [
        {
          "key": "Author",
          "value": "John Doe"
        },
        {
          "key": "Format",
          "value": "Tutorial"
        }
      ],
      "mp4Support": true,
      "panoramic": false,
      "playerId": "pl45KFKdlddgk654dspkze",
      "public": false,
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "source": {
        "uri": "/videos/c188ed58-3403-46a2-b91b-44603d10b2c9/source"
      },
      "tags": [
        "maths",
        "string theory",
        "video"
      ],
      "title": "Maths video",
      "updateddAt": "2019-12-16T08:48:49.000Z",
      "videoId": "vi4k0jvEUuaTdRAEjQ4Prklg"
    },
    {
      "assets": {
        "hls": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/hls/manifest.m3u8",
        "iframe": "<iframe src=\"//embed.api.video/1b9d6ae8-8f57-4b6d-8552-d636926b4f5f?token=831a9bd9-9f50-464c-a369-8e9d914371ae\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/1b9d6ae8-8f57-4b6d-8552-d636926b4f5f?token=831a9bd9-9f50-464c-a369-8e9d914371ae",
        "thumbnail": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg"
      },
      "description": "A description for your video.",
      "metadata": [
        {
          "key": "Author",
          "value": "John Doe"
        },
        {
          "key": "Science Fiction",
          "value": "Cyberpunk"
        },
        {
          "key": "Technology",
          "value": "Computers"
        }
      ],
      "mp4Support": true,
      "panoramic": false,
      "public": false,
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "source": {
        "uri": "/videos/1b9d6ae8-8f57-4b6d-8552-d636926b4f5f/source"
      },
      "tags": [
        "books",
        "short stories"
      ],
      "title": "Video Title",
      "updateddAt": "2019-12-16T08:48:49.000Z",
      "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz"
    },
    {
      "assets": {
        "hls": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/hls/manifest.m3u8",
        "iframe": "<iframe src=\"//embed.api.video/73129412-e320-4b93-99f6-59a85e3cedcd?token=831a9bd9-9f50-464c-a369-8e9d914371ae\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/73129412-e320-4b93-99f6-59a85e3cedcd?token=831a9bd9-9f50-464c-a369-8e9d914371ae",
        "thumbnail": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg"
      },
      "description": "A brief description of the video.",
      "metadata": [
        {
          "key": "Length",
          "value": "Short"
        }
      ],
      "mp4Support": true,
      "panoramic": false,
      "playerId": "pl45KFKdlddgk654dspkze",
      "public": false,
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "source": {
        "uri": "/videos/73129412-e320-4b93-99f6-59a85e3cedcd/source"
      },
      "tags": [
        "General",
        "Videos"
      ],
      "title": "My Video Title",
      "updateddAt": "2019-12-16T08:48:49.000Z",
      "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "currentPageItems": 11,
    "itemsTotal": 11,
    "links": [
      {
        "rel": "self",
        "uri": "https://ws.api.video/videos?currentPage=1"
      },
      {
        "rel": "first",
        "uri": "https://ws.api.video/videos?currentPage=1"
      },
      {
        "rel": "last",
        "uri": "https://ws.api.video/videos?currentPage=1"
      }
    ],
    "pageSize": 25,
    "pagesTotal": 1
  }
}

Request

Query Params
title
string 
optional
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.
Example:
My Video.mp4
tags
array[string]
optional
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.
Example:
"tags": ["captions", "dialogue"]
metadata
array[string]
optional
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.
Example:
[{"key":"Author","value":"John Doe"},{"key":"Format","value":"Tutorial"}]
description
string 
optional
If you described a video with a term or sentence, you can add it here to return videos containing this string.
Example:
New Zealand
liveStreamId
string 
optional
If you know the ID for a live stream, you can retrieve the stream by adding the ID for it here.
Example:
li400mYKSgQ6xs7taUeSaEKr
sortBy
string 
optional
Allowed: publishedAt, title. You can search by the time videos were published at, or by title.
Example:
publishedAt
sortOrder
string 
optional
Allowed: asc, desc. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.
Example:
asc
currentPage
integer 
optional
Choose the number of search results to return per page. Minimum value: 1
Example:
2
pageSize
integer 
optional
Results per page. Allowed values 1-100, default is 25.
Example:
30

Responses

🟢200Success
application/json
Body
data
array[object (video) {13}] 
required
assets
object (videoAssets) 
optional
Collection of details about the video object that you can use to work with the video object.
description
string 
optional
A description for the video content.
Example:
An amazing video explaining string theory.
metadata
array[object (metadata) {2}] 
optional
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 allows you to define a key that allows any value pair.
Example:
[{"key":"Author", "value":"John Doe"}, {"key":"Format", "value":"Tutorial"}]
mp4Support
boolean 
optional
This lets you know whether mp4 is supported. If enabled, an mp4 URL will be provided in the response for the video.
Example:
true
panoramic
boolean 
optional
Defines if video is panoramic.
Example:
false
playerId
string 
optional
The id of the player that will be applied on the video.
Example:
pl45KFKdlddgk654dspkze
public
boolean 
optional
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.
Example:
false
publishedAt
string 
optional
The date and time the API created the video. Date and time are provided using ISO-8601 UTC format.
Example:
2019-12-16T08:25:51.000Z
source
object (videoSource) 
optional
Source information about the video.
tags
array
optional
One array of tags (each tag is a string) in order to categorize a video. Tags may include spaces.
Example:
"tags": ["maths", "string theory", "video"]
title
string 
optional
The title of the video content.
Example:
Maths video
updatedAt
string <date-time>
optional
The date and time the video was updated. Date and time are provided using ISO-8601 UTC format.
Example:
2019-12-16T08:15:51.000Z
videoId
string 
optional
The unique identifier of the video object.
Example:
vi4k0jvEUuaTdRAEjQ4Prklg
pagination
object (Pagination) 
required
Example:
{"currentPage":3,"currentPageItems":20,"itemsTotal":123,"links":{"first":{"rel":"first","uri":"/videos/search?currentPage=1&pageSize=20"},"last":{"rel":"last","uri":"/videos/search?currentPage=6&pageSize=20"},"next":{"rel":"next","uri":"/videos/search?currentPage=4&pageSize=20"},"previous":{"rel":"previous","uri":"/videos/search?currentPage=2&pageSize=20"}},"pageSize":20,"pagesTotal":7}
currentPage
integer 
read-onlyoptional
The current page index.
currentPageItems
integer 
read-onlyoptional
The number of items on the current page.
itemsTotal
integer 
read-onlyoptional
Total number of items that exist.
links
array[object (PaginationLink) {2}] 
required
pageSize
integer 
read-onlyoptional
Maximum number of item per page.
pagesTotal
integer 
read-onlyoptional
Number of items listed in the current page.
🟠400Bad Request
Modified at 2023-08-15 05:52:15
Previous
Show upload token
Next
Create a video
Built with