Getting List of Videos

Send HTTP GET request to API endpoint https://dev.vdocipher.com/api/videos to get the list of all your videos. The video list obtained using this API is paginated by default. This means the response will by default contain the top 20 results, the newest first. You can append the following query parameters to the API request to filter your videos.

Limit - You can change the number of results per request by adding query parameters. The following example request increases the number of videos returned to 40. https://dev.vdocipher.com/api/videos?page=1&limit=40

Page number - You can flip through all your videos by changing the page number. The following HTTP query shows results for videos 41-80. https://dev.vdocipher.com/api/videos?page=2&limit=40

Tags - You can search for videos with a particular tag by passing the tag query parameter:https://dev.vdocipher.com/api/videos?tags={{videoTag1,videoTag2}}. Tags are case-sensitive and using multiple tags (comma-separated) will narrow down the search and ensure every tag is present in the resultant video.

q (searches videoID and title) - You can search for video ID and video titles using the q parameter. https://dev.vdocipher.com/api/videos?q={{partOfVideoIDandTitle}}

folderId - You can list videos only from a specific folder also using the folderId parameter. https://dev.vdocipher.com/api/videos?folderId={{folderId}}. To know more checkout Folder Management APIs.

Folder id can be copied from dashboard as shown below. For saving to top-level, use the folderId: root

Sample Code for Video List

The sample API Secret Key is a1b2c3d4e5. Scroll below for more details on this API.

CURL

curl -X GET \
  'https://dev.vdocipher.com/api/videos?q=query' \
  -H 'Accept: application/json' \
  -H 'Authorization: Apisecret a1b2c3d4e5'

NODE

var request = require('request');

var options = {
  method: 'GET',
  url: 'https://dev.vdocipher.com/api/videos',
  qs: {q: 'query'},
  headers: {
    Accept: 'application/json',
    Authorization: 'Apisecret a1b2c3d4e5',
  },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

PHP

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://dev.vdocipher.com/api/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Accept: application/json",
    "Authorization: Apisecret {{apikey}}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

C#

var client = new RestClient("https://dev.vdocipher.com/api/videos?q=query");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("Authorization", "Apisecret a1b2c3d4e5");
IRestResponse response = client.Execute(request);

Python

import requests

url = "https://dev.vdocipher.com/api/videos"

querystring = {"q":"query"}

headers = {
    'Authorization': "Apisecret a1b2c3d4e5",
    'Accept': "application/json"
}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Ruby

require 'uri'
require 'net/http'

url = URI("https://dev.vdocipher.com/api/videos?q=query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Apisecret a1b2c3d4e5'
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body

Listing

The video list contains most vital information about the videos such as the duration, the storage space, the state of encoding and tags associated with the video. The object structure of API response is as follows:

{
    "count": 3,
    "rows": [
        {
            "id": "{{videoID}}",
            "title": "{{videoTitle}}",
            "description": "{{videoDescription}}",
            "upload_time": {{uploadTimeInUnix}},
            "length": {{inSeconds}},
            "status": "ready",
            "posters": [
                {
                    "width": 854,
                    "height": 480,
                    "posterUrl": "{{posterURL1}}"
                },
                {
                    "width": 427,
                    "height": 240,
                    "posterUrl": "{{posterURL2}}"
                }
            ],
            "tags": [
              {{tag1}},
              {{tag2}}
            ]
        },
        {Second video object},
        {Third video object}
    ]
}

The count parameter is the total number of videos that match the provided filters. The number of actually returned videos will be less than or equal to this number because of pagination.

The maximum number of returned items per API request is 40. Note the page size when setting up the page number value.

How to use this API?

• It is better to use tag filters to get to a desired video instead of getting multi-page responses.
• Take care of the rate-limits when making API requests. Exceeding rate limits can result in errors.
• This API is not built to handle too many requests or serve with low latency or availability. You should never use this API as a dependency for HTTP requests made by general users of your website. In cases where it is desired to show the latest videos in real-time, you should use a caching layer with large expiry time. Using this API directly behind your web-server can result in unexpected issues.
• This API is suited for cron jobs where you might have to check on the encoding status of videos. The cron interval should ideally be 20 minutes or more. The API should have exponential back-off in case of errors and not send bursts of HTTP requests. This will help prevent cases of service denial due to limit exceeding.

Rate-limiting

There are multiple rate limits setup

• IP-based rate limiting
• Key based rate-limiting
• Account based rate-limiting

How to increase the limits?

There can be cases when you might need a higher API rate-limiting. All the above limits are soft-limits i.e. you can request an increase to it for specific cases. If you are an enterprise, we can setup additional dedicated resources as well.

Why multiple rate-limits?

Multiple rate-limits are there to minimize the impact due to a single issue and reduce the number of affected systems. The standard is that IP rate limits will be smallest. This way only a single server will get affected and you could technically switch IP address of server to work around this issue.

What happens in case of exceeding limits?

Exceeding limits can result in denial of service to the IP, key or account. The ban is exercised for a period of 30 minutes to 1 hour depending on the severity of the request flood. In case of repeatedly exceeding limits the ban will be linearly increased.