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, 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

Tag - You can search for videos with a particular tag by passing the tag query parameter:https://dev.vdocipher.com/api/videos?tag={{videoTag}}

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}}

Sample Code for Video List#

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

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

var request = require("request");
var options = {  method: "GET",  url: "https://dev.vdocipher.com/api/videos",  qs: { q: "query" },  headers: {    Accept: "application/json",    "Content-Type": "application/json",    Authorization: "Apisecret a1b2c3d4e5",  },};
request(options, function (error, response, body) {  if (error) throw new Error(error);
  console.log(body);});

$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}}",    "Content-Type: application/json"  ),));
$response = curl_exec($curl);$err = curl_error($curl);
curl_close($curl);
if ($err) {  echo "cURL Error #:" . $err;} else {  echo $response;}

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("Content-Type", "application/json");request.AddHeader("Authorization", "Apisecret a1b2c3d4e5");IRestResponse response = client.Execute(request);

import requests
url = "https://dev.vdocipher.com/api/videos"
querystring = {"q":"query"}
headers = {    'Authorization': "Apisecret a1b2c3d4e5",    'Content-Type': "application/json",    'Accept': "application/json"    }
response = requests.request("GET", url, headers=headers, params=querystring)
print(response.text)

require 'uri'require 'net/http'
url = URI("https://dev.vdocipher.com/api/videos?q=query")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)request["Authorization"] = 'Apisecret a1b2c3d4e5'request["Content-Type"] = 'application/json'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 retuned items per API request is 40. This number can be increased to 100. 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.