Viddler Developers » The Viddler API, version 2

The Viddler API exposes Viddler’s key features to those that would like to build custom solutions on top of Viddler’s video platform. In order to use Viddler’s API you must have a Viddler account and an API key. To access your API key please log into Viddler.com and navigate to ‘Your Username > Settings > API’.

NOTE: If you do not see API access under your settings you do not have access to our API. Please call us at 1-888-444-1119 to enable API access.

We ask that developers use the API responsibly. This means that we’d like you to:

Limit requests to no more than one per second, and only one request at a time.
Cache response results for as long as possible when circumstances allow for it.
Protect user credentials by storing them no longer than necessary or at all.
Report issues through our Helpdesk which is included with your account.

API V2 End-point: http://api.viddler.com/api/v2/

API Changelog: http://developers.viddler.com/documentation/api-changelog/

API Overview

Request format and methods

REST (simplified) – http request with all argument passed as http parameters. Simplified version with only support for two http methods:
GET – methods which don’t change anything (get data)
POST – methods which change underlying data model (create, change, delete)
multipart POST – file uploads only
SSL – supported for all API methods.

Response format

Support for 4 response formats: XML, JSON, JSONP and PHP
JSONP will always call jsonViddlerAPI(response)
Content-Type HTTP response code will change depending on response format
API Endpoint: http(s)://api.viddler.com/api/v2/methodname.format

XML example:

Request: GET http://api.viddler.com/api/v2/viddler.api.getInfo.xml?key=API_KEY

Response:
Content-Type: text/xml;charset=UTF-8
X-Viddler-Node: api0
<viddler_api>
  <version>2.0.0</version>
</viddler_api>

JSON example:

Request: GET http://api.viddler.com/api/v2/viddler.api.getInfo.json?key=API_KEY

Response:
Content-Type: application/json;charset=UTF-8
X-Viddler-Node: api0
{
  "viddler_api":{
    "version":"2.0.0"
  }
}

PHP example (response may be used with PHP unserialize function to get PHP array):

Request: GET http://api.viddler.com/api/v2/viddler.api.getInfo.php?key=API_KEY

Response:
Content-Type: text/plain
X-Viddler-Node: api0
a:1:{
  s:11:"viddler_api";a:1:{
    s:7:"version";s:5:"2.0.0";
  }
}

Note: application/x-httpd-php PHP Content-Type is not handled well by HTTP server therefore PHP response Content-Type has been changed to text/plain.

Data types

date, datetime – unix timestamp (number of seconds elapsed since Jan 1st 1970 UTC). For dates – time part will be ignored. Dates passed as method parameters use YYYY-MM-DD format.
booleans – responses will use “0″ and “1″ only but request may contain 0/1, true/false, yes/no values – any other will be considered as false
floating point numbers – will be scaled to two digits after a dot if not explicitly stated otherwise
nulls – API won’t return “null” values. Null values will be represented as empty string – optional ( value

Error Codes and Descriptions

This is a list of the default error codes that any method could return at any given time. Some methods can return errors specific to them but the response format will be the same.

Error #	Description, Cause, Resolution
1	An internal error has occurred. Cause: A bug in the API. Resolution: Contact us.
2	Bad argument format. Cause: You didn’t supply the right information for an argument. Resolution: Be sure to submit the correct format for the arguments you’re supplying.
3	Unknown argument specified. Cause: One of the arguments is unknown. Resolution: Perhaps you misspelled the argument?
4	Missing required argument for this method. Cause: An argument, like sessionid, is required and it wasn’t specified. Resolution: Be sure to consult the method’s documentation to be sure you’re supplying all of the required arguments.
5	No method specified. Cause: The request did not include a method.
6	Unknown method specified. Cause: The method provided is not a valid method. Resolution: Check the available methods and be sure the spelling of the method is correct.
7	API key missing. Cause: The request didn’t include an API key or the argument for the API key is misspelled.
8	Invalid or unknown API key specified. Cause: Be sure you are using a valid API key. Resolution: If your API key should be valid and isn’t contact us.
9	Invalid or expired sessionid. Cause: The sessionid hasn’t been used and has expired. Resolution: Use viddler.users.auth to create a new API key.
10	Used HTTP method is not allowed for this API method. Cause: You are using a GET when you should be using POST or vice-versa. Resolution: Try using HTTP POST instead of HTTP GET or refer to the docs.
11	Method call not allowed. Cause: Your API key security level restricts calling this method. Resolution: If you need the method that you’re calling contact us.
12	API key disabled. Cause: The API key or account has been flagged for abuse or violation of TOS. Resolution: Contact us to restore the API key.
13	Invalid data sent with request. Cause: The data sent with the request is not valid (e.g. A zip file was sent instead of a video.) Resolution: Check the file type of the data before sending it to the API.
14	Bad or invalid SSL state.
15	Invalid response format requested. Cause: The response format you requested is not supported. Resolution: Choose a format that the API supports; PHP, JSON, XML.
100	Whatever you requested was Not Found. Cause: You asked for a resource that does not exist.
101	The action is forbidden. Cause: You are attempting to do something that your API key does not allow.
102	The account has been suspended. Cause: The account you’re trying to use has been suspended. Resolution: Contact us to see why.
103	Invalid password. Cause: The password provided is incorrect.
104	Terms Not Accepted. Cause: When submitted a sign up, the TOS was not agreed to.
105	Username already exists. Cause: The username provided is already taken.
106	This email address already exists. Cause: The email address provided for a sign up is already in use.
200	The file provided is too large. Cause: The video file you provided is too large. Resolution: Provide a smaller file.
202	Upload error (e.g. invalid multipart format request) Cause: An upload must be a multipart form-data encoded request. Resolution: Follow the documentationclosely.
203	Uploading has been disabled, probably temporarily for maintenance. Cause: Viddler is doing routine maintenance. Resolution: Please wait and try again later.
204	Upload resume responds with “bad content range”.
205	Upload resume responds with “bad server”.
206	Upload resume responds with “not possible, file deleted”.
207	Upload resume responds with “not overlapping range”.
208	Upload resume responds with “too much data”.
209	Upload resume responds with “not possible, no valid upload found”.

Error Response Format

  <code>4</code>
  missing required parameter
node may or may not be included in the error response.

Authentication

As a good rule of thumb you should authenticate as a first step of your script. Even if your videos are publicly available and don’t require a session to manipulate them. This way if you ever change your video permissions your application won’t break.

To properly authenticate and return a valid session id you must use the method ‘viddler.users.auth‘ and pass your username and password. The result will return a valid session id which can be used for subsequent calls that require an id.

If you fail to authenticate correctly the API will return an error response. Be sure to properly catch these errors so that your applications know if you have successfully authenticated.

If you are an account with sub-accounts you will have to authenticate as each sub-account in order to do anything pertaining to one of your sub-accounts. Your master account session id will not be valid for your sub-accounts.

Error handling

Each API method response should be checked for the following to ensure it doesn’t contain any errors:

Error response in desired format + appropriate HTTP result code,
Only HTTP 200 result code will indicate successful request,
Error responses will hold error code, error description and optional error details

Examples:

XML:

<error>
  <code>4</code>
  <description>missing required parameter</description>
  <details>message</details>
</error>

JSON:

{"error":{
  "code":"4",
  "description":"missing required parameter",
  "details":"message"
}}

PHP:

a:1:{
  s:5:"error";a:3:{
    s:4:"code";s:1:"4";
    s:11:"description";s:26:"missing required parameter";
    s:7:"details";s:7:"message";
  }
}

Warnings

Sometimes there is need to provide some additional information about things that just happen, especially when there is general success in processing request (ex. one of provided values where ignored). In such cases result object will contain “warnings” array with “warning” object which “description” field holding additional information.

Methods

Everything you need to know about Viddler’s API methods.

Method naming

Methods naming convention are as such - [scope].[group].[action]

scope – method scope – always “viddler” for public methods,
group – what this method affects – “users”, “videos”, “groups” etc.
action – real action – “addComment”, “getByUser” etc.

Examples:

viddler.users.auth
viddler.videos.getByUser

Each method call requires passing the “api_key” parameter.

Paged lists response format

Paged lists will use a unified response format in order to return list metadata instead of pure list items. This way all of the responses that return a list of results will have a very similar, if not the same, schema. Envelope example:

PHP

Array (
  [list_result] => Array (
  [page] => 1
  [per_page] => 1
  [sort] => uploaded-desc sort tag is added on sort enabled methods
  [featured_videos] => Array tag name depends on data it holds
  ([0] => Array (
    ...))))

JSON

{
  "list_result": {
  "page": "1",
  "per_page": "1",
  "sort": "uploaded-desc",
  "featured_videos": [
{
...
}]}}

XML

<?xml version="1.0" encoding="UTF-8"?>
  <list_result>
    <page>1</page>
    <per_page>1</per_page>
    <sort>uploaded-desc</sort>
    <featured_videos>
    ...
    </featured_videos>
  </list_result>

List of Methods

viddler.api.echo

GET
This method is used for testing purposes only. Simply call this method to make sure the API is responding fine.

Parameters

message – string – required

Example

GET /api/v2/viddler.api.echo.php?key=API_KEY&message=hello

Array (
  [echo_response] => Array (
    [message] => hello)
  )

viddler.api.getInfo

GET
Returns the current version information of the API.

Parameters

No params

Example

GET /api/v2/viddler.api.getInfo.php?key=API_KEY

Array (
  [viddler_api] => Array (
    [version] => 2.2.0
    )
  )

viddler.encoding.getSettings

GET
Returns the current encoding options for an account.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.encoding.getSettings.json?sessionid=SESSIONID&key=YOUR_KEY

{
  "encoding_settings":{
    "use_source_for_playback":"1",
    "encoding_profiles":[
      {
        "id":"8",
        "name":"360p",
        "format":"mp4",
        "enabled":"1",
        "bitrate":"200",
        "allowed_bitrates":"200,400,600,800",
        "dimensions":"640x360"
      },
      {
        "id":"3",
        "name":"480p",
        "format":"mp4",
        "enabled":"1",
        "bitrate":"800",
        "allowed_bitrates":"400,600,800,1000,1500",
        "dimensions":"854x480"
      },
      {
        "id":"4",
        "name":"720p",
        "format":"mp4",
        "enabled":"1",
        "bitrate":"2000",
        "allowed_bitrates":"800,1000,1500,2000,2500",
        "dimensions":"1280x720"
      },
      {
        "id":"7",
        "name":"1080p",
        "format":"mp4",
        "enabled":"1",
        "bitrate":"4000",
        "allowed_bitrates":"1500,2000,2500,3000,4000,5000",
        "dimensions":"1920x1080"
      },
      {
        "id":"5",
        "name":"3GP",
        "format":"3gp",
        "enabled":"1",
        "bitrate":"100",
        "allowed_bitrates":"50,100,200,500",
        "dimensions":"320x180"
      },
      {
        "id":"6",
        "name":"WebM",
        "format":"webm",
        "enabled":"1",
        "bitrate":"800",
        "allowed_bitrates":"400,600,800,1000",
        "dimensions":"854x480"
      }
    ]
  }
}

viddler.encoding.getStatus

GET
Returns the encoding status for a specific video. This method can only return data 2 days old or newer.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.encoding.getStatus.xml?sessionid=SESSIONID&key=API_KEY&

<?xml version="1.0" encoding="UTF-8"?>
<list_result>
<files>
<file>
<id>728a0c5d4029</id>
<status>processing</status>
<ext>flv</ext>
<source>0</source>
<flash>off</flash>
<iphone>na</iphone>
<ipad>na</ipad>
<itunes>na</itunes>
<profile_id>2</profile_id>
<video_id>3fe80c6d</video_id>
<encoding_status>encoding</encoding_status>
<encoding_progress>60</encoding_progress>
</file>
<file>
<id>728a0c5d4028</id>
<status>processing</status>
<ext>flv</ext>
<source>0</source>
<flash>off</flash>
<iphone>na</iphone>
<ipad>na</ipad>
<itunes>na</itunes>
<profile_id>2</profile_id>
<video_id>3fe80c6d</video_id>
<encoding_status>encoding</encoding_status>
<encoding_progress>0</encoding_progress>
</file>
</files>
</list_result>

Encoding statuses
- new – waiting in queue for encode,
- encoding – currently encoding,
- success
- error
- cancelling
- cancelled

viddler.encoding.getStatus2

GET
This method is the same as viddler.encoding.getStatus except that it groups files better for users to easily find what they are looking for. We could not easily update the previous method without causing complications with external applications.

Parameters

sessionid – string – required
video_id – string – optional

Example

viddler.encoding.encode

POST
Request to re-encode a video file.

Parameters

sessionid – string – required
video_id – string – required
profile_id – number – which encoding profile to use? based on viddler.encoding.getOptions

Example

Response is same as for viddler.encoding.getStatus

viddler.encoding.cancel

POST
Cancel encoding a specific video file.

Parameters

sessionid – string – required
file_id – number – required

Example

Response is same as for viddler.encoding.getStatus

viddler.encoding.setSettings

POST
Set the encoding options for a specific acount.

Parameters

use_source_for_playback – boolean - This flag determines if source file uploaded will be used for both Flash and HTML5 playback (if provided source is in proper format)
profile_#_bitrate – number – sets profile # (1,2,3,4) bitrate. Only by profile predefined values can be used. If you’ll use an invalid value – invalid data error will be returned. Currently all profiles allow setting bitrates from the list: 400, 600, 800, 1000, 1500
sessionid – required

Example

GET /api/v2/viddler.encoding.setSettings.php?sessionid=SESSIONID&key=YOUR_KEY&profile_2_bitrate=1000 - Response is the same as for viddler.encoding.getSettings

viddler.logins.add

POST
Adds a new login to user account when the main account has multi-user sign-on enabled. You must have this feature enabled for your account. Please call us at 1-888-444-1119 to enable for you account.

Parameters
All parameters that end in ‘_permissions’ support a comma delimited list of options submitted for each param. The options range from manage, create, read, update and delete. Each parameter lists what it supports for setting.

sessionid – string – required
login – string (100) – required – The login username you would like to create
name – string (100) – required – The name of the user
email – string (100) – required – The email of the user
password – string (100) – required – The password of the user
analytics_permissions – string – optional – options: manage
api_settings_permissions – string – optional – options: manage
api_access_permissions – string – optional – options: manage
billing_settings_permissions – string – optional – options: manage
branding_settings_permissions – string – optional – options: manage
encoding_settings_permissions – string – optional – options: manage
interaction_settings_permissions – string – optional – options: manage
invoices_permissions – string – optional – options: manage
itunes_settings_permissions – string – optional – options: manage
logins_permissions – string – optional – options: create, read, update and delete
player_settings_permissions – string – optional – options: manage
playlists_permissions – string – optional – options: manage
privacy_settings_permissions – string – optional – options: manage
profile_permissions – string – optional – options: manage
recorder_permissions – string – optional – options: manage
subaccounts_permissions – string – optional – options: create, read, update and delete
support_permissions – string – optional – options: manage
videos_permissions – string – optional – options: create, read, update and delete
vidgets_permissions – string – optional – options: manage
playlist_ids – string – optional – A comma delimited list of playlist IDs this user can view. Can be set to ‘all’.

Example

POST /api/v2/viddler.logins.add.json?sessionid=SESSIONID&key=YOUR_KEY&login=johnny&name=Johnny%20Mnemonic&email=johnny@cyber.co&password=PASS&videos_permissions=read,update,delete

Error Response

{
  "errors": { "login": "Please enter a username" }
}

Response

{
  "login": {
    "login": "johnny",
    "owner": "0",
    "name": "Johnny Mnemonic",
    "created_at": "1234567890",
    "email": "johnny@cyber.co",
    "status": "1",
    "permissions": {
      "videos": { "permissions": "read,update,delete" }
    }
  }
}

viddler.logins.delete

POST
Remove a login from your user list

Parameters

sessionid – string – required
login – string – required – The login username you would like to remove

Example

POST /api/v2/viddler.logins.delete.json?sessionid=SESSIONID&key=YOUR_KEY&login=johnny

Response

{ "success": null }

viddler.logins.get

GET
Return the current permissions for a specific user.

Parameters

sessionid – string – required
login – string – required – The login username you would like to return information for.

Example

GET /api/v2/viddler.logins.get.json?sessionid=SESSIONID&key=YOUR_KEY&login=johnny

Response

{
  "login": {
    "login": "johnny",
    "owner": "0",
    "name": "Johnny Mnemonic",
    "created_at": "1234567890",
    "email": "johnny@cyber.co",
    "status": "1",
    "permissions": {
      "videos": { "permissions": "read,update,delete" }
    }
  }
}

viddler.logins.list

GET
Return a list of all current users attached to your account.

Parameters

sessionid – string – required
login – string – optional – Pass the login to search by login
email – string – optional – Pass the email to search by login
query – string – optional – works like login OR name OR email – exact match for either of those. If present – login, name, email parameters are being ignored
permission_type – string – optional – one of permission types
permission_level – string – required if permission_type is set – options: manage,create,read,update,delete
object_id – string – optional – can search by playlist_id or any other permission that support ids
sort – string – optional – login-asc (default), login-desc, name-asc, name-desc, email-asc, email-desc

Example

GET /api/v2/viddler.logins.get.json?sessionid=SESSIONID&key=YOUR_KEY&login=johnny

Response

{
  "list_result": {
    "page": "1",
    "per_page": "10",
    "sort": "email-desc",
    "logins":
	    0: {
		    "login": "johnny",
		    "owner": "0",
		    "name": "Johnny Mnemonic",
		    "created_at": "1234567890",
		    "email": "johnny@cyber.co",
		    "status": "1",
		    "permissions": {
		      "videos": { "permissions": "read,update,delete" }
	    }
  }
  }
}

viddler.logins.update

POST
Updates a current login.

sessionid – string – required
login – string – required – The login username you would like to create
name – string – optional – The name of the user
email – string – optional – The email of the user
password – string – optional – The password of the user
analytics_permissions – string – optional – options: manage
api_settings_permissions – string – optional – options: manage
api_access_permissions – string – optional – options: manage
billing_settings_permissions – string – optional – options: manage
branding_settings_permissions – string – optional – options: manage
encoding_settings_permissions – string – optional – options: manage
interaction_settings_permissions – string – optional – options: manage
invoices_permissions – string – optional – options: manage
itunes_settings_permissions – string – optional – options: manage
logins_permissions – string – optional – options: create, read, update and delete
player_settings_permissions – string – optional – options: manage
playlists_permissions – string – optional – options: manage
privacy_settings_permissions – string – optional – options: manage
profile_permissions – string – optional – options: manage
recorder_permissions – string – optional – options: manage
subaccounts_permissions – string – optional – options: create, read, update and delete
support_permissions – string – optional – options: manage
videos_permissions – string – optional – options: create, read, update and delete
vidgets_permissions – string – optional – options: manage
playlist_ids – string – optional – A comma delimited list of playlist IDs this user can view. Can be set to ‘all’.

Example

POST /api/v2/viddler.logins.update.json?sessionid=SESSIONID&key=YOUR_KEY&login=johnny&name=Johnny%20Mnemonic&email=johnny@cyber.co&password=PASS&videos_permissions=read,update,delete

Response

{
  "login": {
    "login": "johnny",
    "owner": "0",
    "name": "Johnny Mnemonic",
    "created_at": "1234567890",
    "email": "johnny@cyber.co",
    "status": "1",
    "permissions": {
      "videos": { "permissions": "read,update,delete" }
    }
  }
}

viddler.playlists.addVideo

POST
Add a video to a standard playlist. The same video may be added several times to one playlist.

Parameters

sessionid – string – required
playlist_id – string – required
video_id – string – required (comma delimited list of video IDs (100 max))

Example

POST /api/v2/viddler.playlists.addVideo.json?sessionid=SESSIONID&key=YOUR_KEY&playlist_id=YOUR_PLAYLIST_ID&video_id=YOUR_VIDEO_ID

- Response is the same as for viddler.playlists.getDetails for modified playlist_id

viddler.playlists.create

POST
Create a playlist. Regular playlist represents user defined videos. Smart playlist updates in realtime returning videos matching selected filtering rules.

Parameters

sessionid – string – required
name – string – required (100 character max)
type – string – optional (regular or smart, defaults to regular)
playlist_visibility – string – optional (public or private, defaults to private)
Regular Playlist Params (all optional)
- video_ids – string (comma delimited video ids to be added to a regular playlist)
Smart Playlist Params (all optional)
- users – string (comma delimited usernames, defaults to your username)
- max_age – number (how old videos should be returned. Integer number representing videos age in days. Ex. 10 – will return videos at uploaded in last 10 days / empty by default)
- tags – string (comma separated tags names)
- visibility – string (public or private, empty by default)
- min_views – number (minimal number of views, empty by default)
- max_views – number (maximum number of views, empty by default)
- min_update_date – string (date formatted as: YYYY-MM-DD, empty by default)
- max_update_date – string (date formatted as: YYYY-MM-DD, empty by default)
- sort – string (uploaded-desc, uploaded-asc, views-desc, views-asc, defaults to uploaded-desc)

Example
Regular playlist

POST /api/v2/viddler.playlists.create.json?sessionid=SESSIONID&key=API_KEY&name=my+list&video_ids=aa1192ea,aa1192ea

Smart playlist

POST /api/v2/viddler.playlists.create.json?sessionid=SESSIONID&key=API_KEY&name=my+smart+list&type=smart&users=sandieman,drkn&max_age=30&min_views=10

Response in both cases is the same as for viddler.playlists.getDetails – representing current playlist state

viddler.playlists.setDetails

POST
Update playlist details. The method takes the same parameters as viddler.playlists.create except for type (which can’t be changed). Response is the same as viddler.playlists.getDetails

Parameters

sessionid – string – required

viddler.playlists.delete

POST
Delete a playlist. Caution: This operation cannot be undone.

Parameters

sessionid – string – required
playlist_id – string – required

Example

POST /api/v2/viddler.playlists.delete.json?sessionid=SESSIONID&key=API_KEY&playlist_id=7187326c7717e5ea

- Response is the same as for viddler.playlists.list

viddler.playlists.getDetails

GET
Get playlist details with all its videos. Videos list for smart lists generate in the real time

Parameters

sessionid – string – optional (required if your account or playlist is private)
playlist_id – string – optional (if you want a specific playlist, specify it)
page – number – optional (the current page to return, default to 1)
per_page – number – optional (how many playlists to show per return, defaults to 10)

Example

GET /api/v2/viddler.playlists.getDetails.json?sessionid=SESSIONID&key=API_KEY&playlist_id=728b326c7717e5ea

{
  "list_result": { standard list result envelope
  "page": "1",
  "per_page": "10",
  "total": "10",
  "playlist": { playlist details
  "id": "728b326c7717e5ea",
  "name": "my list",
  "type": "smart",
  "visibility": "public",
  "rules": { section visible only for smart lists - showing all filter applied
    "users": "drkn,jhammer,axemaster",
    "min_views": "10"
  }
},
"videos_list": [
  { video details object - same as returned by viddler.videos.getDetails
    "id": "73e7156f",
    "status": "ready",
    "author": "jhammer",
    "title": "t",
    "length": "11",
    "description": "t\n",
    "url": "VIDEO URL",
    "thumbnail_url": "THUMBNAIL_URL",
    "permalink": "PERMALINK",
    "html5_video_source": "FILE_URL",
    "audio_only": "0",
    "view_count": "69",
    "upload_time": "1276693288",
    "made_public_time": "1276661136",
    "favorite": "0", boolean - did currently logged in user favorite the video
    "comment_count": "0",
    "age_limit": 10, or empty if not set
    "files": [{
      "id": "728a0c5f4621e1ee",
      "status": "ready",
      "ext": "avi",
      "type": "video/x-msvideo",
      "width": "720",
      "height": "480",
      "size": "7782400",
      "url": "FILE_URL",
      "html5_video_source": "",
      "source": "1",
      "flash": "na",
      "iphone": "na",
      "ipad": "na",
      "itunes": "na"
    },
    {
      "id": "728a0c5f4620e1ee",
      "status": "ready",
      "ext": "flv",
      "type": "video/x-flv",
      "width": "640",
      "height": "426",
      "size": "704696",
      "url": "FILE_URL",
      "html5_video_source": "",
      "source": "0",
      "flash": "on",
      "iphone": "na",
      "ipad": "na",
      "itunes": "na",
      "profile_id": "1",
      "profile_name": "360p",
    },
    {
      "id": "728a0c5f4623e1ee",
      "status": "ready",
      "ext": "mp4",
      "type": "video/mp4v-es",
      "width": "640",
      "height": "426",
      "size": "692807",
      "url": "FILE_URL",
      "html5_video_source": "SOURCE_URL",
      "source": "0",
      "flash": "na",
      "iphone": "on",
      "ipad": "off",
      "itunes": "on",
      "profile_id": "3"
    }]
},
  ... the list continues
  ]}
}

viddler.playlists.list

GET
List all playlists for an account.

Parameters

sessionid – string – required
page – number – optional (the current page to return, default to 1)
per_page – number – optional (how many playlists to show per return, defaults to 10)

Example

GET /api/v2/viddler.playlists.list.json?sessionid=SESSIONID&key=API_KEY

{
"list_result": { ... standard list result envelope ...
"page": "1",
"per_page": "10",
"playlists": [
  {
    "id": "7280326c7717e5ea",
    "name": "the best one",
    "type": "regular",
    "visibility": "private"
  },
{
"id": "7287326c7717e5ea",
"name": "smart list",
"type": "smart",
"visibility": "public",
"rules": {
  "users": "drkn",
  "min_upload_date": "2010-02-10",
  "min_views": "10"
}}]}}

viddler.playlists.getByUser

GET
List all user’s public playlists (or public and private if you’re asking for own playlists. In such case the method will act as viddler.playlists.list)

Parameters

sessionid – string – optional (required if your account is private)
user – string – optional (if no sessionid it is required)
page – number – optional (the current page to return, default to 1)
per_page – number – optional (how many playlists to show per return, defaults to 10)

Example

Response is the same as for viddler.playlists.list

viddler.playlists.moveVideo

GET
Reorder videos in regular playlist.

Parameters

sessionid – string – required
playlist_id – string – required
from – number – required (indexes with number starting at 0)
to – number – required (indexes with number starting at 0)

Example

POST /api/v2/viddler.playlists.moveVideo.json?sessionid=SESSIONID&key=API_KEY&playlist_id=7280326c7717e5ea&from=0&to=1

- Response is the same as for viddler.playlists.getDetails for altered playlist_id

viddler.playlists.removeVideo

GET
Remove a video from regular playlist.

Parameters

sessionid – string – required
playlist_id – string – required
position – number – required (indexes with number starting at 0)

Example

POST /api/v2/viddler.playlists.removeVideo.json?sessionid=SESSIONID&key=API_KEY&playlist_id=7280326c7717e5ea&position=0

- Response is the same as for viddler.playlists.getDetails for altered playlist_id

viddler.resellers.getSubaccounts

GET
List all subaccounts under your account. Only applies to reseller accounts. Other accounts do not have access to this method.

Parameters

sessionid – string – required
page – number – optional (page number to return, defaults to 1)
per_page – number – optional (total sub-accounts to return, defaults to 10, max is 100)
sort – string – option (“username-asc”, ”username-desc”, ”videos-asc”, ”videos-desc”, ”bandwidth-asc”, ”bandwidth-desc”, ”storage-asc”, ”storage-desc”)

Example

GET /api/v2/viddler.resellers.getSubaccounts.php?sessionid=SESSIONID&key=YOUR_KEY

Array
(
    [list_result] => Array
        (
            [page] => 1
            [per_page] => 10
            [subaccounts] => Array
                (
                    [0] => Array
                        (
                            [username] => SUB_USER
                            [plan] => Array(PLAN_INFO)

                        )...

viddler.resellers.removeSubaccount

GET
Remove / delete a sub-account from your account list. This method is only active to reseller accounts.

Parameters

sessionid – string – required
subaccount – string – required

Example

GET /api/v2/viddler.resellers.removeSubaccount.php?sessionid=SESSIONID&key=YOUR_KEY
Array
(
    [list_result] => Array
        (
            [page] => 1
            [per_page] => 10
            [subaccounts] => Array
                (
                    [0] => Array
                        (
                            [username] => SUB_USER
                            [plan] => Array(PLAN_INFO)

                        )...

viddler.videos.addClosedCaptioning

POST
Add new closed captioning file for a specific video. All uploaded closed captioning files are enabled by default. The first uploaded file is default for a video.

Parameters

sessionid – string – required if video is not public
video_id – string – required
language – string – required – The language of the file (Max Characters: 50)
default – boolean – optional
closed_captioning_url – string – required (Max Charaters: 1024)

Example

GET /api/v2/viddler.videos.addClosedCaptioning.json?sessionid=SESSIONID&key=KEY&video_id=VIDEO_ID&language=English&closed_captioning_url=http://www.yoursite.com/file.srt

{
  "video":{
    //SAME RESULTS AS getByUser - Below is the CC info returned
    "closed_captioning_list":[
      {
        "id":"7a85326c7717e5ea",
        "enabled":"1",
        "language":"English",
        "type":"SRT",
        "file_size":"101880",
        "file_url":"SRT_FILE",
        "default":"1"
      }
    ]
  }
}

viddler.videos.comments.add

POST
Adds a text comment to the specified video (Both timed and global).

Parameters

sessionid – string – required
video_id – string – required
text – string – required (1024 character max)
timepoint – number – optional (used if a timed comment)

Example

viddler.videos.comments.get

GET
Get comments for a video. If logged in and querying comments for own video – all comments with any moderation status will be returned. If quering comments as logged out or for not owned video – only approved comments will be returned if the video itself is public.

Parameters

sessionid – string – required if video is not public
video_id – string – required
parent_id – string – optional – comment parent ID if you want to get the responses to that particular comment
per_page – number – optional
page – number – optional

Example

GET /api/v2/viddler.videos.comment.get.json?sessionid=SESSIONID&key=KEY&video_id=VIDEO_ID

{
  "list_result":{
    "page":"1",
    "per_page":"10",
    "sort":"date-desc",
    "comments_list":[
      {
        "id":"7286015d7515e7e8",
        "type":"text",
        "author":"phpfunk",
        "rating":"0",
        "replies_count":"0",
        "text":"This is another comment example.",
        "add_time":"1335198425",
        "comments_moderation":{
          "status":"1",
          "obscenity_filter":"ex"
        }
      },
      {
        "id":"7286015f7515e7e8",
        "type":"text",
        "author":"phpfunk",
        "rating":"0",
        "replies_count":"2",
        "text":"This is a comment example.",
        "add_time":"1335198405",
        "comments_moderation":{
          "status":"1",
          "obscenity_filter":"ex"
        }
      }
    ]
  }
}

viddler.videos.comments.remove

POST
Removes a text comment from a video.

Parameters

sessionid – string – required
comment_id – number – required

Example

POST /api/v2/viddler.videos.comment.remove.php?sessionid=SESSIONID&key=API_KEY&comment_id=322

- Response is the same as viddler.videos.comments.add.

viddler.videos.delClosedCaptioning

POST
Remove an existing closed captioning file.

Parameters

sessionid – string – required if video is not public
closed_captioning_id – string – required

Example

GET /api/v2/viddler.videos.delClosedCaptioning.json?sessionid=SESSIONID&key=KEY&closed_captioning_id=CC_ID

{
  "video":{
    //SAME RESULTS AS viddler.videos.getDetails - Below is the CC info returned
    "closed_captioning_list":[

    ]
  }
}

viddler.videos.getDetails

GET
Return the full details and all associated data for a specific video.

Parameters

sessionid – string – required
video_id – string – optional (required if not using url)
url – string – optional (required if not using video_id)
status – boolean – optional (0 = only files ready to view, 1 = all files, defaults to 0)
include_comments or add_comments – boolean – optional (0 = no comments (faster response), 1 = comments (slower response), defaults to 0)
add_embed_code – boolean – optional (0 = no embed code, 1 = embed code, defaults to 0)
add_profile – boolean – optional (0 = no profile info, 1 = profile info, defaults to 0)
add_view_token – boolean – optional (0 = no token, 1 = video token used for viewing, defaults to 0)

Example

GET /api/v2/viddler.videos.getDetails.php?sessionid=SESSIONID&key=YOUR_KEY&video_id=VIDEO_ID

{
  "video":{
    "id":"VIDEO_ID",
    "status":"ready",
    "author":"USER",
    "title":"TITLE'",
    "length":"124",
    "description":" ",
    "age_limit":"",
    "url":"VIDDLER_VIDEO_URL",
    "thumbnail_url":"THUMBNAIL_URL",
    "permalink":"PERMALINK_URL",
    "html5_video_source":"HTML5_SRC_URL",
    "audio_only":"0",
    "view_count":"0",
    "impression_count":"0",
    "upload_time":"1336398328",
    "made_public_time":"",
    "favorite":"0",
    "comment_count":"0",
    "tags":[
      {
        "type":"global",
        "text":"TAG"
      }
    ],
    "thumbnails_count":"11",
    "thumbnail_index":"0",
    "permissions":{
      "view":{
        "level":"private"
      },
      "embed":{
        "level":"private"
      },
      "tagging":{
        "level":"private"
      },
      "commenting":{
        "level":"private"
      },
      "download":{
        "level":"private"
      }
    },
    "comments_moderation":{
      "level":"",
      "to_review":"0"
    },
    "display_aspect_ratio":"16:9",
    "files":[
      {
        "id":"7287045b4427d1dc9441ad8da0620e49",
        "status":"ready",
        "ext":"mp4",
        "type":"video/mp4",
        "width":"1280",
        "height":"720",
        "size":"33209832",
        "url":"URL",
        "html5_video_source":"URL",
        "display_aspect_ratio":"16:9",
        "source":"1",
        "flash":"on",
        "iphone":"na",
        "ipad":"on",
        "itunes":"on",
        "profile_id":"",
        "profile_name":"Source"
      },
      {
        "id":"7287045b4427d1deb9277855957171ba",
        "status":"ready",
        "ext":"mp4",
        "type":"video/mp4",
        "width":"640",
        "height":"360",
        "size":"8520280",
        "url":"URL",
        "html5_video_source":"URL",
        "display_aspect_ratio":"16:9",
        "source":"0",
        "flash":"off",
        "iphone":"on",
        "ipad":"off",
        "itunes":"off",
        "profile_id":"3",
        "profile_name":"480p"
      },
      {
        "id":"7287045b4427d1d84cd1ff08919b83b9",
        "status":"ready",
        "ext":"3gp",
        "type":"video/3gpp",
        "width":"320",
        "height":"180",
        "size":"2838919",
        "url":"URL",
        "html5_video_source":"",
        "display_aspect_ratio":"16:9",
        "source":"0",
        "flash":"na",
        "iphone":"na",
        "ipad":"na",
        "itunes":"na",
        "profile_id":"5",
        "profile_name":"3gp"
      },
      {
        "id":"7287045b4427d1da1219ed736339a114",
        "status":"ready",
        "ext":"webm",
        "type":"video/webm",
        "width":"640",
        "height":"360",
        "size":"12516059",
        "url":"URL",
        "html5_video_source":"",
        "display_aspect_ratio":"16:9",
        "source":"0",
        "flash":"na",
        "iphone":"na",
        "ipad":"na",
        "itunes":"na",
        "profile_id":"6",
        "profile_name":"webm"
      }
    ],
    "closed_captioning_list":[

    ]
  }
}

Deleted files will be shown in the response until the time the files are fully purged (deleted) Viddler still holds file information with “purged” status but it won’t show in the API response. Notice that there is no “HD” property. HD is reported as FLV with appropriate dimension – at least one of width or height must match 1280×720. HD FLV may also be reported as file with profile_id = FlashHD.id = 2. The backend doesn’t decide whenever FlashHD videos will be HQ or HD. It’s up to flash player how to display those videos.

viddler.videos.setClosedCaptioning

POST
Update closed captioning details on a previously uploaded file.

Parameters

sessionid – string – required if video is not public
closed_captioning_id – string – required
language – string – optional – The language of the file (Max Characters: 50)
enabled – boolean – optional
default – boolean – optional (cannot be set to default if disabled)

Example

GET /api/v2/viddler.videos.setClosedCaptioning.json?sessionid=SESSIONID&key=KEY&closed_captioning_id=CC_ID&language=English&enabled=1&default=1

{
  "video":{
    //SAME RESULTS AS viddler.videos.getDetails - Below is the CC info returned
    "closed_captioning_list":[
      {
        "id":"7a85326c7717e5ea",
        "enabled":"1",
        "language":"English",
        "type":"SRT",
        "file_size":"101880",
        "file_url":"SRT_FILE",
        "default":"1"
      }
    ]
  }
}

viddler.videos.setDetails

POST
Update the information for a specific video.

Parameters

sessionid – string – required
video_id – string – required (a single or comma delimited list of video ids to update, if multiple ids are submitted changes will be applied to all videos. Multiple video updates support the following sub-options: age_limit, tags, view_perm, embed_perm, download_perm, commenting_perm, tagging_perm, remove_tags)
title – string – optional
description – string – optional
thumbnail_index – number – optional
age_limit – number – optional (for users with age gate enabled, – value between 9 and 99 or empty to reset)
tags – string – optional (comma separated list of tags to add. Single video will replace all current tags, multiple videos will append the tags)
remove_tags – string – optional (comma separated list of tags to remove from videos)
view_perm – string – optional (public, private, invite, embed)
view_reset_secret – boolean – optional (set to 1 to reset secret key, defaults to 0)
embed_perm – string – optional
commenting_perm – string – optional
download_perm – string – optional
tagging_perm – string – optional
file_#_flash – boolean – optional (turn flash feature on a file on or off. If video file has been created based on “1″ encoding profile – it can’t be disabled)
file_#_iphone – boolean – optional (turn iphone feature on or off)
file_#_ipad – boolean – optional (turn ipad feature on or off)
comments_moderation_level – number – optional (0 = no moderation, 1 = hold all comments, 2 = deny comments that may contain profanity, 3 = hold comments that may contain profanity)

Response

Same as for viddler.videos.getDetails

viddler.videos.delete

POST
Delete a video.

Parameters

sessionid – string – required
video_id – string – required

Response

Array (
  [success] => Array ( ))

viddler.videos.delFile

POST
Delete a specific video file (such as a 3GP video file) for a specific video.

Parameters

sessionid – string – required
file_id – string – required (a file ID acquire with viddler.videos.getDetails)

Response

Same as for viddler.videos.getDetails with status=1

viddler.users.getProfile

GET
Get the public information for a profile. Can only get profile information for public profiles.

Parameters

sessionid – string – optional (required if getting your profile if private)
user – string – optional (required if not sessionid)

Example

GET /api/v2/viddler.users.getProfile.php?key=API_KEY&sessionid=SESSIONID

Array (
[user] => Array (
[username] => phpfunk
[first_name] => Jeff
[last_name] => Johns
[about_me] =>
[avatar] =>
[age] => 30
[video_upload_count] => 10
[video_watch_count] => 0
[homepage] => http://www.viddler.com
[gender] => m
[company] => test1
[city] =>
[friend_count] => 1
[favorite_video_count] => 10
))

viddler.users.logout

GET
Logs you out and clears all session cookies if any are set.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.users.getProfile.php?key=YOUR_KEY&sessionid=YOUR_SESSION

Array
(
    [success] => Array
        (
        )

)

viddler.users.setProfile

GET
Update your profile information.

Parameters

sessionid – string – required
homepage – string – optional
avatar_url – string – optional

Example

POST /api/v2/viddler.users.setProfile.php?key=YOUR_KEY&first_name=MyFirstName

- Response is the same as on viddler.users.getProfile

viddler.users.register

POST
Create a new Viddler account. This method can be used only by resellers to create new account. Please contact support to get access to this method if needed.

Parameters

sessionid – string – required
user – string – required
password – string – required
termsaccepted – boolean – required
email – string – required
fname – string – required
lname – string – required
company – string – required

Example

POST /api/v2/viddler.users.register.json?sessionid=SESSIONID&key=YOUR_KEY&user=testapi2&email=test@test.com&termsaccepted=1&fname=test&lname=test&password=mypass

{
"user": {
"username": "testapi2",
"first_name": "test",
"last_name": "test",
"about_me": "",
"avatar": "",
"age": "0",
"video_upload_count": "0",
"video_watch_count": "0",
"homepage": "",
"gender": "",
"company": "",
"city": "",
"friend_count": "0",
"favorite_video_count": "0"
}}

viddler.users.getSettings

GET
Return account settings.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.users.getSettings.json?sessionid=SESSIONID&key=API_KEY

{
  "settings":{
    "visible":"1",
    "show_account":"1",
    "gravatar":"0",
    "default_view_permission":"private",
    "default_comment_permission":"private",
    "default_download_permission":"private",
    "default_embed_permission":"private",
    "default_tag_permission":"private",
    "whitelisted_domains":"",
    "tagging_enabled":"1",
    "commenting_enabled":"1",
    "embedding_enabled":"1",
    "download_enabled":"1",
    "show_related_videos":"0",
    "video_browser_enabled":"0",
    "get_link_enabled":"1",
    "clicking_through_enabled":"1",
    "embed_code_type":"4",
    "delivery_methods":{
      "progressive":"1",
      "streaming":"1",
      "adaptive":"1"
    },
    "video_delivery_method":"2",
    "replaceable_video":"1",
    "hd_playback":"1",
    "mobile_playback":"1",
    "default_video_permalink":"",
    "custom_embed_url":"",
    "notifications":{
      "email_encoding_end":"0",
      "email_comment_received":"0",
      "email_tag_added":"0",
      "email_commented_video_received_comment":"0",
      "email_newsletter":"0"
    },
    "comments_moderation":{
      "status":"1",
      "level":"0",
      "to_review":"0"
    },
    "comscore":{
      "enabled":"1",
      "distribution_platform":"",
      "location":"",
      "owner":"",
      "segment_level_reporting":"",
      "show_level_reporting":"",
      "price":""
    },
    "liverail":{
      "manageable":"0",
      "enabled":"1",
      "id":"ID"
    }
  }
}

viddler.users.setSettings

POST
Set account settings. All parameters are optional besides sessionid

Parameters – All optional params will default to current setting if not submitted

sessionid – string – required
visible – boolean – optional (0 = private, 1 = public)
gravatar – boolean – otional (0 = do not use gravatar, 1 = use gravatar)
default_view_permission – string – optional (private, invite, embed, public)
default_comment_permission – string – optional (private or public)
default_download_permission – string – optional (private or public)
default_embed_permission – string – optional (private or public)
default_tag_permission – string – optional (private or public)
whitelisted_domains – string – optional (Comma delimited list of whitelisted domains – max 1024 characters)
clicking_through_enabled – boolean – optional (0 = no click-throughs from video, 1 = click-throughs enabled)
video_browser_enabled – boolean – optional (0 = do not show videos at the end of the video, 1 = show videos)
embed_code_type – integer – optional (1 = Legacy, 2 = WordPress, 3 = Flash w/ HTML5 Fallback, 5 = iframe – You must have access to multiple embed types to update correctly)
video_delivery_method – number – optional (0 = Progressive Download, 1 = RTMP Streaming | You must have access to both delivery methods to be able to change)
hd_playback – boolean – optional (0 = do not allow your users to view in HD, 1 = allow)
mobile_playback – boolean – optional (0 = do not allow your users to view on mobile devices 1 = allow)
default_video_permalink – string – optional
custom_embed_url – string – optional (The custom url to use for your embeds, you must set the URLs cname to viddler.com for this to work)
comments_moderation – number – optional (0 = no moderation, 1 = Hold all comments, 2 = Automatically deny posts that may profanity, 3 = Hold all posts that may contain profanity)
video_delivery_method – number – optional (0 = progressive, 1 = streaming, 3 = adaptive)
default_tags -string – optional (comma-delimited list of tags to be applied to all newly uploaded videos. Can only be used if your account has access to this feature)
email_encoding_end – boolean – optional (0 = do not email me when my encodes are finished, 1 = email me)
email_comment_received – boolean – optional (0 = do not email me when comments are received, 1 = email me)
email_tag_added – boolean – optional (0 = do not email me when tags are received, 1 = email me)
email_commented_video_received_comment – boolean – optional (0 = do not email me when a video comment is posted, 1 = email me)
email_newsletter – boolean – optional (0 = do not subscribe to newsletter, 1 = subscribe)

Response

GET /api/v2/viddler.users.setSettings.json?sessionid=SESSIONID&key=YOUR_KEY&comments_moderation=2&email_tag_enabled=1&whitelisted_domains=yoursite.com,*.yorsite.com

- Same as for viddler.users.getSettings

viddler.videos.getAdsStatus

GET

Parameters

sessionid – string – required
video_id – string – required

Example

GET /api/v2/viddler.videos.getAdsStatus.php?sessionid=SESSIONID&key=API_KEY&video_id=VIDEO_ID

Array (
  [video_ads_status] => Array (
    [status] => enabled
    [video_id] => d627c61d ) )

viddler.videos.disableAds

POST
Disable ads off for specified videos.

Parameters

sessionid – string – required
video_ids – string – required (comma separated list of videos ids)

Example

POST /api/v2/viddler.videos.disableAds.php?sessionid=SESSIONID&key=API_KEY&video_ids=VIDEO_ID,VIDEO_ID2

Array (
  [result] => Array (
    [changed] => 1 how many videos have been affected
    [video_ids] => d627c61d coma separated affected video ids )

viddler.videos.enableAds

POST
Turn ads off for specified videos.

Parameters

sessionid – string – required
video_ids – string – required (comma separated list of videos ids)

Example

POST /api/v2/viddler.videos.disableAds.php?sessionid=SESSIONID&key=API_KEY&video_ids=VIDEO_ID,VIDEO_ID2

- Response same as for viddler.videos.disableAds

viddler.videos.getByUser

GET
Returns a list of videos for a specified account.

Parameters

sessionid – string – optional (required if getting your videos on a private account or for private videos)
page – number – optional (defaults to 1)
per_page – number – optional (defaults to 10)
user – string – optional (required if not using sessionid)
status – boolean – optional
sort – string – optional (title-asc, title- desc, uploaded-asc, uploaded-desc, views-asc, views-desc, defaults to uploaded-desc)
tags – string – optional (comma delimited list of tags)
visibility – string – optional (comma delimited list of options which are below)
- private = Private Videos
- public = Public Videos
- invite = Invite Only Videos
- embed = Domain Restricted Videos

Example

GET /api/v2/viddler.videos.getByUser.json?sessionid=SESSIONID&key=API_KEY

{
  "list_result":{
    "page":"1",
    "per_page":"10",
    "total":"10",
    "sort":"uploaded-desc",
    "video_list":[
      {
        "id":"88d701fb",
        "status":"ready",
        "author":"phpfunk",
        "title":"Comment Example",
        "length":"2",
        "description":"",
        "age_limit":"",
        "url":"VIDEO URL",
        "thumbnail_url":"THUMBNAIL URL",
        "permalink":"PERMALINK",
        "html5_video_source":"",
        "audio_only":"0",
        "view_count":"0",
        "impression_count":"0",
        "upload_time":"1334950932",
        "made_public_time":"",
        "favorite":"0",
        "comment_count":"3",
        "thumbnails_count":"1",
        "thumbnail_index":"0",
        "permissions":{
          "view":{
            "level":"invite"
          },
          "secreturl":"SECRET URL IF APPLICABLE",
          "embed":{
            "level":"private"
          },
          "tagging":{
            "level":"private"
          },
          "commenting":{
            "level":"public"
          },
          "download":{
            "level":"private"
          }
        },
        "comments_moderation":{
          "level":"",
          "to_review":"0"
        },
        "display_aspect_ratio":"16:9",
        "files":[
          {
            "id":"72820d5f4912e0ef",
            "status":"ready",
            "ext":"flv",
            "type":"video/x-flv",
            "width":"0",
            "height":"0",
            "size":"10518",
            "url":"URL TO VIDEO",
            "html5_video_source":"",
            "display_aspect_ratio":"",
            "source":"1",
            "flash":"on",
            "iphone":"na",
            "ipad":"na",
            "itunes":"na",
            "profile_id":"",
            "profile_name":"Source"
          }
        ],
        "closed_captioning_list":[
          {
            "id":"7a85326c7717e5ea",
            "enabled":"1",
            "language":"English",
            "type":"SRT",
            "file_size":"101880",
            "file_url":"URL TO CC FILE",
            "default":"1"
          }
        ]
      },
      ...

viddler.videos.getEmbedCodeTypes

GET
Return a list of the embed code types for your account.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.videos.getEmbedCodeTypes.json?key=API_KEY

{
  "list_result": {
    "embed_code_types": [{
      "id": "1",
      "name": "Legacy"
      },
      {
      "id": "2",
      "name": "Wordpress"
      },
      {
      "id": "3",
      "name": "Flash with HTML5 mobile fallback support"
    }]
  }
}

viddler.videos.getEmbedCode

GET
Return a proper embed code for a specific video.

Parameters

sessionid – string – optional (required if your account is private or the video is private)
video_id – string – required
width – number – optional
height – number – optional
player_type – string – optional (full, simple or mini, defaults to full)
wmode – string – optional (transparent, opaque, window, defaults to transparent)
autoplay – boolean – optional
branding – boolean – optional (show video owner’s branding, defaults to true)
offset – number – optional (playback offset in seconds)
embed_code_type – number – optional (embed code type number, listed at viddler.videos.getEmbedCodeTypes)
flashvar – string – optional (can specify any flashvar as the key and it’s value as value. IE: displayUser=jeff

Example

GET /api/v2/viddler.videos.getEmbedCode.json?key=API_KEY&video_id=aa1192ea&width=400

{
  "video": {
  "video_id": "aa1192ea",
  "embed_code": "the embed code",
  }
}

viddler.videos.prepareUpload

GET
Returns the end-point and token for a new upload session.

Parameters

sessionid – string – required
allow_replace – boolean – optional – Set to true if you are allowing the incoming upload to replace an already existing video

Example

  GET /api/v2/viddler.videos.prepareUpload.xml?key=API_KEY&sessionid=SESSIONID

<?xml version="1.0" encoding="UTF-8"?>
<upload>
  <endpoint>http://www.viddler.com/uploadnode/upload/uploadvideo</endpoint>
  <token>u81989c2a3eef4531b0c94db25b07f0b2b0d9fcda</token>
</upload>

viddler.videos.upload

POST
After you obtain your upload endpoint and token you can then upload them using our direct upload methodology or using cURL. Documentation and examples are listed below.

Examples

viddler.videos.uploadProgress

GET
Return the status of an upload.

Parameters

sessionid – string – required
token – string – required (return from viddler.videos.prepareUpload)

Example

GET /api/v2/viddler.videos.uploadProgress.json?sessionid=SESSIONID&key=API_KEY&token=TOKEN

Response (In progress)
{
  "upload_progress": {
    "total_uploaded": "2200000",
    "total_bytes": "2207388",
    "percent": "57.32",
    "status": "1"
  }
}

Response (Complete)
{
  "upload_progress": {
    "total_uploaded": "2207388",
    "total_bytes": "2207388",
    "percent": "100.00",
    "status": "2"
  }
}

Response (Cancel)
{
  "upload_progress": {
    "total_uploaded": "2200000",
    "total_bytes": "2207388",
    "percent": "57.32",
    "status": "3"
  },
  "error": {
    "code": "CODE",
    "description": "DESCRIPTION",
    "details": "DETAILS"
  }
}

Response (Error)
{
  "upload_progress": {
    "total_uploaded": "2200000",
    "total_bytes": "2207388",
    "percent": "57.32",
    "status": "4"
  },
  "error": {
    "code": "CODE",
    "description": "DESCRIPTION",
    "details": "DETAILS"
  }
}

viddler.videos.setPermalink

POST
Change a video’s permalink. (Or, where the user goes when they click on the video.)

Parameters

sessionid – string – required
video_id – string – required
permalink – string – optional (if not passed it will be reset to default)

Response

Response is the same as for viddler.videos.getDetails

viddler.videos.getRecordToken

GET
Return a record token to use with Viddler’s Flash video recorder.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.videos.getRecordToken.xml?sessionid=SESSIONID&key=API_KEY

<?xml version="1.0" encoding="UTF-8"?>
<record_token>
  <value>1d5e612ab3e9eacd44524b4e14</value>
</record_token>

viddler.users.auth

GET
Authenticate an account. Returns session for reuse.

Parameters

user – string – required
password – string – required
get_record_token – boolean – optional (0 = no token, 1 = get token)

Example

GET /api/v2/viddler.users.auth.php?key=API_KEY&user=drkn&password=12345678&get_record_token=1

Array (
  [auth] => Array (
    [sessionid] => 29b32e2128f8f25fa844524b4e175
    [record_token] => 2155173128f8f25fae44524b4e33f )
  )

viddler.users.getPlayerBranding

GET
Returns your player branding configuration.

Parameters

sessionid – string – required

Example

GET /api/v2/viddler.users.getPlayerBranding.php?sessionid=SESSIONID&key=YOUR_KEY

Array
(
    [player_branding] => Array
        (
            [logo_url] => LOGO_URL
            [logo_click_url] =>
            [logo_width] => 100
            [logo_height] => 100
            [logo_flash_version] => 0
            [logo_visible] => 0
            [logo_offset_x] => 10
            [logo_offset_y] => 10
            [logo_align] => tl
            [shade_dark] => 0
            [advanced_options] => 0
            [simple_color] => #8a8a8a
            [control_bar] => #e40c0c
            [bhover] => #ff1ff9
            [bidle] => #acf000
            [bclicked] => #0bf9ca
            [pidle] => #05ff21
            [phover] => #4523fb
            [pclicked] => #fa6800
            [timeplayed] => #23a8fb
            [timeloaded] => #f747fa
            [timebackground] => #faf005
            [enable_stripes] => 1
        )

)

viddler.videos.search

GET
Search for videos. If searching for your videos and your account is private or any videos are private you must pass in your session id.

Parameters

sessionid – string – optional (required to search your videos if private)
type – string – optional (yourvideos, user, allvideos, defaults to yourvideos)
sort – string – optional (uploaded-desc, upload-asc, views-desc, views-asc, defaults to uploaded-desc)
per_page – number – optional (defaults to 10, max of 100)
page – number – optional (defaults to 1)
Type: ‘yourvideos’ Params
- query – string – required (keyword to search for in video title, description, global and timed tags, if all videos send query=*)
- min_upload_date – string – optional (minimum date that the video was uploaded | format: YYYY-MM-DD)
- max_upload_date – string – optional (maximum date that the video was uploaded | format: YYYY-MM-DD)
- max_age – number – optional (videos uploaded in the last ‘x’ amount of days)
Type: ‘user’ Params
- user – string – required
Type: ‘allvideos’ Params
- query – string – required (keyword to search for in video title, description, global and timed tags, if all videos send query=*)

Example

viddler.users.setPlayerBranding

POST
Sets your player branding options. All options are optional other than your sessionid. Color formats are in hexadecimal format with preceding pound sign (IE: #rrggbb)

Parameters – All optional params if not submitted will remain as the current value

sessionid – string – required
logo_url – string – optional (URL to the logo to use for your player)
logo_click_url – string – optional (URL for the logo to click through to. Leave blank for no click through)
logo_offset_x – number – optional (Total pixels to offset your logo from the player on the x axis)
logo_offset_y – number – optional (Total pixels to offset your logo from the player on the y axis)
logo_align – string – optional (Aligns your logo (choices: br, bl, tl, tr)
logo_visible – boolean – optional (Whether or not to show your logo)
shade_dark – boolean – optional (Set to true to use a darker shade, false to use a lighter shade)
enable_stripes – boolean – optional (Whether or not to use stripes in the load bar)
simple_color – color – optional (Main player color)
control_bar – color – optional (Main control bar color)
bhover – color – optional (Button hover color)
bidle – color – optional (Button idle color)
bclicked – color – optional (Button clicked color)
phover – color – optional (Plus button hover color)
pidle – color – optional (Plus button idle color)
pclicked – color – optional (Plus button clicked color)
timeplayed – color – optional (Time played bar color)
timeloaded – color – optional (Time loaded bar color)
timebackground – color – optional (Time bar background color)

Example

POST /api/v2/viddler.users.setPlayerBranding.php?sessionid=SESSIONID&key=YOUR_KEY&logo_url=LOGO_URL&logo_align=tl

Array
(
    [player_branding] => Array
        (
            [logo_url] => LOGO_URL
            [logo_click_url] =>
            [logo_width] => 100
            [logo_height] => 100
            [logo_flash_version] => 0
            [logo_visible] => 0
            [logo_offset_x] => 10
            [logo_offset_y] => 10
            [logo_align] => tl
            [shade_dark] => 0
            [advanced_options] => 0
            [simple_color] => #8a8a8a
            [control_bar] => #e40c0c
            [bhover] => #ff1ff9
            [bidle] => #acf000
            [bclicked] => #0bf9ca
            [pidle] => #05ff21
            [phover] => #4523fb
            [pclicked] => #fa6800
            [timeplayed] => #23a8fb
            [timeloaded] => #f747fa
            [timebackground] => #faf005
            [enable_stripes] => 1
        )

)

viddler.videos.setThumbnail

POST or MULTIPART POST
Sets video thumbnail. You can either set video timepoint or upload own thumbnail for a video.

Parameters

sessionid – string – required
video_id – string – required
timepoint – integer – optional (using regular POST, if not using file)
file – video file – optional (using MULTIPART POST, if not using timepoint)

Example

Same as for viddler.videos.getDetails

Viddler

Developers

Documentation

The Viddler API, version 2

API Overview

Request format and methods

Response format

Data types

Error Codes and Descriptions

Error Response Format

Authentication

Error handling

Methods

Method naming

Paged lists response format

List of Methods

viddler.api.echo

viddler.api.getInfo

viddler.encoding.getSettings

viddler.encoding.getStatus

viddler.encoding.getStatus2

viddler.encoding.encode

viddler.encoding.cancel

viddler.encoding.setSettings

viddler.logins.add

viddler.logins.delete

viddler.logins.get

viddler.logins.list

viddler.logins.update

viddler.playlists.addVideo

viddler.playlists.create

viddler.playlists.setDetails

viddler.playlists.delete

viddler.playlists.getDetails

viddler.playlists.list

viddler.playlists.getByUser

viddler.playlists.moveVideo

viddler.playlists.removeVideo

viddler.resellers.getSubaccounts

viddler.resellers.removeSubaccount

viddler.videos.addClosedCaptioning

viddler.videos.comments.add

viddler.videos.comments.get

viddler.videos.comments.remove

viddler.videos.delClosedCaptioning

viddler.videos.getDetails

viddler.videos.setClosedCaptioning

viddler.videos.setDetails

viddler.videos.delete

viddler.videos.delFile

viddler.users.getProfile

viddler.users.logout

viddler.users.setProfile

viddler.users.register

viddler.users.getSettings

viddler.users.setSettings

viddler.videos.getAdsStatus

viddler.videos.disableAds

viddler.videos.enableAds

viddler.videos.getByUser

viddler.videos.getEmbedCodeTypes

viddler.videos.getEmbedCode

viddler.videos.prepareUpload

viddler.videos.upload

viddler.videos.uploadProgress

viddler.videos.setPermalink

viddler.videos.getRecordToken

viddler.users.auth

viddler.users.getPlayerBranding

viddler.videos.search

viddler.users.setPlayerBranding

viddler.videos.setThumbnail

Search

Navigation

About Us

Services

Need Help?