Viki Platform

API v4

This is the documentation for version 4 of Viki's official API. This API is still a work in progress, which means periodic changes are expected.

All API is accessed through the api.viki.io/v4/ endpoints.

Authentication

Sign up

Register your application at the Viki application dashboard. You may use your normal Viki account or create a separate account to manage your applications. You will be granted a Client ID and a Client Secret.

Making requests

An SHA1-HMAC signature, timestamp and application id should be included with every request in order to authenticate it.

The timestamp is the current time (unix timestamp) assigned to the t parameter. The signature is the url (including querystring) + body text (if any). Your application's secret is the hmac's key.

For example, given an application id of 9001 and a secret of orange as well as the following GET request:

/v4/movies.json?sort=views

The first thing we would do is add our app and t paremeters:

/v4/movies.json?sort=views&app=9001&t=1356482778

(assuming that today is December 26, 12:45am)

We would then get the SHA1-HMAC value of the above. In node.js, this looks like:

crypto = require('crypto');
hmac = crypto.createHmac('sha1', 'orange');
hmac.update('/v4/movies.json?sort=views&app=9001&t=1356482778');
sig = hmac.digest('hex');

And append it to our querystring:

/v4/movies.json?sort=views&app=9001&t=1356482778&sig=be84d78da2b1ce800fe745ec782ded2304233390

In the case of an invalid timestamp (if the servers are out of sync), the following error will be returned:

{"error":"stale timestamp","current_timestamp":SERVER_TIMESTAMP}

The command should be re-issued using the returned SERVER_TIMESTAMP;

Signature Headers

As an alternative to using the t and sig query parameters, you can also use the timestamp and signature headers. Use whichever you prefer, but do note that using headers plays nicer with caches (the ever-changin parameters in the URL aren't cache-friendly). Our own caching layer is timestamp and signature aware, but browsers aren't.

Formats

Most API resources are retrieved in JSON. The only exception are Subtitles which are retrieved in SRT. Use the appropriate extension (.json or .srt) as part of your request. Leaving out the format extension will cause an error. For example:

/v4/movies.json

will return a list of movie resources in JSON format, and calling:

/v4/movies/50/subtitles.srt

will return the subtitles for the specified movie in srt.

JSONP

If a request to a .json endpoint also has a callback querystring parameter, a jsonp response will be returned.

Mailing list

There is a mailing list for the Viki API were you can write for support: viki-platform@googlegroups.com

To see the group of already asked questions please direct to our google group page.