To get started with the REST API you will need your 'API key' and your 'Secret Key' both of which can be found in the settings section of the dashboard.
You will also need some knowledge on how to develop apps using a server side technology such as PHP, Ruby or C#.
For more information on REST API's please read the wiki article.
Note: It is strongly advised not to use the REST API direct from JavaScript as this would expose your 'Secret Key' which, as the name suggests, should be kept secret at all times!
The current version of the REST API is v1.1 and can be accessed here:
https://api.kenseimedia.com/v1.1/
We use basic auth over HTTPS to authenticate your API calls. Use your 'API Key' as the username and your 'Secret Key' as the password.
The Kensei REST API currently handles 2 formats: JSON and XML. All methods allow you to choose which format you wish to use but the default is JSON.
We currently provide a C# wrapper to the REST API. You can download the wrapper here: We will be providing wrappers for Ruby and PHP shortly.
GET /categories.{format}
Status: 200 OK
[
{
"id":1234,
"name":"corporate"
},
{
"id":5678,
"name":"animation"
}
]
Status: 200 OK
<categories> <category> <id>1234</id> <name>corporate</name> </category> <category> <id>5678</id> <name>animation</name> </category> </categories>
POST /categories.{format}
<category> <name>Excellent adventures</name> </category>
{
"name": "Excellent adventures"
}
Status: 201 Created
Location: https://[kensei api address]/{api version}/{api key}/Categories/{new category id}.xml
<category> <id>43</id> <name>Excellent adventures</name> </category>
Status: 201 Created
kensei api address]/{api version}/{api key}/Categories/{new category id}.json
{
"id": 43,
"name": "Excellent adventures"
}
PUT /categories{category id}.{format}
<category> <id>43</id> <name>Bogus journeys</name> </category>
{
"id": 43,
"name": "Bogus journeys"
}
Status: 200 OK
<category> <id>43</id> <name>Bogus journeys</name> </category>
Status: 200 OK
{
"id": 43,
"name": "Bogus journeys"
}
DELETE /categories{category id}.{format}
Status: 200 OK
GET /collections/{collection id}.{format}
Status: 200 OK
<collection> <id>3ce2c94f-47db-4ace-b0ef-fdf62d436523</id> <type>VideoChannel</type> <status>Private</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> <dateCeated>2012-11-01T16:12:00</dateCreated> <dateModified>2012-11-01T16:12:00</dateModified> <totalItems>1</totalItems> </collection>
Status: 200 OK
{
"id": "3ce2c94f-47db-4ace-b0ef-fdf62d436523",
"type": "VideoChannel",
"collectionStatus": "Private",
"title": "Promotional videos",
"description": "A collection of videos promoting our products.",
"dateCreated": "2012-11-01T16:12:00",
"dateModified": "2012-11-01T16:12:00",
"totalItems": 1
}
GET /collections.{format}
Status: 200 OK
<collections> <collection> <id>3ce2c94f-47db-4ace-b0ef-fdf62d436523</id> <type>VideoChannel</type> <status>Public</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> <dateCeated>2012-11-01T16:12:00</dateCreated> <dateModified>2012-11-01T16:12:00</dateModified> <totalItems>1</totalItems> </collection> <collection> <id>b9ea50b4-9034-4eea-90e6-f5930fc61d79</id> <type>VideoChannel</type> <status>Private</status> <title>Showreels</title> <description>A collection of my latest showreels</description> <dateCeated>2012-05-30T10:54:00</dateCreated> <dateModified>2012-05-30T10:56:00</dateModified> <totalItems>1</totalItems> </Collection> </Collections>
Status: 200 OK
[
{
"id":"3ce2c94f-47db-4ace-b0ef-fdf62d436523",
"type":"VideoChannel",
"collectionStatus":"Public",
"title":"Promotional videos",
"description":"A collection of videos promoting our products.",
"dateCreated":"2012-11-01T16:12:00",
"dateModified":"2012-11-01T16:12:00",
"totalItems":1
},
{
"id":"b9ea50b4-9034-4eea-90e6-f5930fc61d79",
"type":"VideoChannel",
"status":"Private",
"title":"Showreels",
"description":"A collection of my latest showreels",
"dateCreated":"2012-05-30T10:54:00",
"dateLastModified":"2012-05-30T10:56:00",
"totalItems":1
}
]
POST /collections.{format}
<collection> <type>VideoChannel</type> <status>Private</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> </collection>
{
"type": "VideoChannel",
"collectionStatus": "Private",
"title": "Promotional videos",
"description": "A collection of videos promoting our products."
}
Status: 201 Created
Location: https://[kensei api address]/{api version}/{api key}/Collections/{new collection id}.xml
<collection> <id>3ce2c94f-47db-4ace-b0ef-fdf62d436523</id> <type>VideoChannel</type> <status>Private</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> <dateCeated>2012-11-01T16:12:00</dateCreated> <dateModified>2012-11-01T16:12:00</dateModified> <totalItems>1</totalItems> </collection>
Status: 201 Created
kensei api address]/{api version}/{api key}/Collections/{new collection id}.json
{
"id":"3ce2c94f-47db-4ace-b0ef-fdf62d436523",
"type":"VideoChannel",
"collectionStatus":"Public",
"title":"Promotional videos",
"description":"A collection of videos promoting our products.",
"dateCreated":"2012-11-01T16:12:00",
"dateModified":"2012-11-01T16:12:00",
"totalItems":1
}
PUT /collections/{collection id}.{format}
<collection> <id>3ce2c94f-47db-4ace-b0ef-fdf62d436523</id> <type>VideoChannel</type> <status>Private</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> </collection>
{
"id":"3ce2c94f-47db-4ace-b0ef-fdf62d436523",
"type":"VideoChannel",
"collectionStatus":"Public",
"title":"Promotional videos",
"description":"A collection of videos promoting our products."
}
Status: 200 OK
<collection> <id>3ce2c94f-47db-4ace-b0ef-fdf62d436523</id> <type>VideoChannel</type> <status>Private</status> <title>Promotional videos</title> <description>A collection of videos promoting our products.</description> <dateCeated>2012-11-01T16:12:00</dateCreated> <dateModified>2012-11-01T16:12:00</dateModified> <totalItems>1</totalItems> </collection>
Status: 200 OK
{
"id":"3ce2c94f-47db-4ace-b0ef-fdf62d436523",
"type":"VideoChannel",
"collectionStatus":"Public",
"title":"Promotional videos",
"description":"A collection of videos promoting our products.",
"dateCreated":"2012-11-01T16:12:00",
"dateModified":"2012-11-01T16:12:00",
"totalItems":1
}
DELETE /collections/{collection id}.{format}
Status: 200 OK
GET /media/{media item id}.{format}
Status: 200 OK
<mediaItem> <id>427b54f7-686f-45a0-984a-a717405e7672</id> <title>Nerdzilla defeats Geekazoid</title> <type>video</type> <status>public</status> <description>Geeky robot fights with nerdy dinosaur and the dinosaur wins.<description /> <dateCreated>2011-01-04T13:27:00</dateCreated> <userId>def41fc5-7298-439e-8cf4-22d9f3d374bd</userId> <username>bob_roperts</username> <originalFile>01111010101.mp4</originalFile> <producer>kensei films</producer> <dateProduced>2008-12-01T16:36:00</dateProduced> <duration>00:01:06</duration> <currentRating>4.76</currentRating> <totalViewed>137</totalViewed> <totalFavourites>12</totalFavourites> <category>Portfolio<category /> <tags> <string>fun</string> <string>robot</string> <string>dinosaur</string> </tags> <files> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4</url> <label>lo</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4</url> <label>hi</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4</url> <label>hd</label> </mediafile> </files> <thumbnail>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</thumbnail> <still>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</still> <embed><iframe src='http://api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe></embed> </mediaItem>
Status: 200 OK
{
"id":"427b54f7-686f-45a0-984a-a717405e7672",
"title":"Nerdzilla defeats Geekazoid",
"type":"video",
"status":"public",
"description":"Geeky robot fights with nerdy dinosaur and the dinosaur wins",
"dateCreated":"2008-12-01T16:36:00",
"userId":"def41fc5-7298-439e-8cf4-22d9f3d374bd",
"username":"bob_roberts",
"originalFile":"01111010101.mp4",
"producer":"kensei films",
"dateProduced":"2008-12-01T16:36:00",
"duration":"00:01:06",
"currentRating":4.76,
"totalViewed":43,
"totalFavourites":12,
"category":"Portfolio",
"tags":[
"fun",
"robot",
"dinosaur"
],
"files":[
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4",
"label":"lo"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4",
"label":"hi"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4",
"label":"hd"
}
],
"thumbnail":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1.jpg",
"still":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg",
"embed":"<iframe src='http://api.kenseimedia.com/v1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe>"
}
GET /media.{format}
Status: 200 OK
<mediaItems> <mediaItem> <id>427b54f7-686f-45a0-984a-a717405e7672</id> <title>Nerdzilla defeats Geekazoid</title> <type>video</type> <status>public</status> <description>Geeky robot fights with nerdy dinosaur and the dinosaur wins.</description> <dateCreated>2011-01-04T13:27:00</dateCreated> <userId>def41fc5-7298-439e-8cf4-22d9f3d374bd</userId> <username>bob_roperts</username> <originalFile>01111010101.mp4</originalFile> <producer>kensei films</producer> <dateProduced>2008-12-01T16:36:00</dateProduced> <duration>00:01:06</duration> <currentRating>4.76</currentRating> <totalViewed>137</totalViewed> <totalFavourites>12</totalFavourites> <category>Portfolio</category> <tags> <string>fun</string> <string>robot</string> <string>dinosaur</string> </tags> <files> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4</url> <label>lo</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4</url> <label>hi</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4</url> <label>hd</label> </mediafile> </files> <thumbnail>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</thumbnail> <still>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</still> <embed><iframe src='http://api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe></embed> </mediaItem> <mediaItem> <id>0717cc41-16c9-4122-ba0b-011ba581d2e8</id> <title>Black quartz</title> <type>audio</type> <status>private</status> <description>nice track, no drums, just guitars</description> <dateCreated>2010-11-30T13:24:00</dateCreated> <userId>3a55d950-da32-4611-922c-1467750e2a37</userId> <username>daveyravey</username> <originalFile>01 Black Quartz.m4a</originalFile> <producer>barry</producer> <dateProduced>2010-11-30T13:24:00</dateProduced> <duration>00:03:16</duration> <currentRating>4.45</currentRating> <totalViewed>2134</totalViewed> <totalFavourites>234</totalFavourites> <category>Music</category> <tags> <string>music</string> <string>guitars</string> <string>folk</string> </tags> <files> <mediafile> <url>http://cdn.kenseimedia.com/14/b/j/i/0717cc41-16c9-4122-ba0b-011ba581d2e8/0717cc41-16c9-4122-ba0b-011ba581d2e8.mp3</url> <label>mp3</label> </mediafile> </files> <thumbnail/> <still/> <embed><iframe src='http://test.api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/0717cc41-16c9-4122-ba0b-011ba581d2e8.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe></embed> </mediaItem> </mediaItems>
Status: 200 OK
[
{
"id":"427b54f7-686f-45a0-984a-a717405e7672",
"title":"Nerdzilla defeats Geekazoid",
"type":"video",
"status":"public",
"description":"Geeky robot fights with nerdy dinosaur and the dinosaur wins",
"dateCreated":"2008-12-01T16:36:00",
"userId":"def41fc5-7298-439e-8cf4-22d9f3d374bd",
"username":"bob_roberts",
"originalFile":"01111010101.mp4",
"producer":"kensei films",
"dateProduced":"2008-12-01T16:36:00",
"duration":"00:01:06",
"currentRating":4.76,
"totalViewed":43,
"totalFavourites":12,
"category":"Portfolio",
"tags":[
"fun",
"robot",
"dinosaur"
],
"files":[
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4",
"label":"lo"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4",
"label":"hi"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4",
"label":"hd"
}
],
"thumbnail":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1.jpg",
"still":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg",
"embed":"<iframe src='http://api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe>"
},
{
id: "0717cc41-16c9-4122-ba0b-011ba581d2e8",
title: "Black quartz",
type: "audio",
status: "private",
description: "nice track, no drums, just guitars",
dateCreated: "2010-11-30T13:24:00",
userId: "3a55d950-da32-4611-922c-1467750e2a37",
username: "daveyravey",
originalFile: "01 Black Quartz.m4a",
producer: "barry",
dateProduced: "2010-11-30T13:24:00",
duration: "00:03:16",
currentRating: 4.45,
totalViewed: 2134,
totalFavourites: 234,
category: "Music",
tags: [
"music",
"guitars",
"folk"
],
files: [
{
url: "http://cdn.kenseimedia.com/14/b/j/i/0717cc41-16c9-4122-ba0b-011ba581d2e8/0717cc41-16c9-4122-ba0b-011ba581d2e8.mp3",
label: "mp3"
}
],
thumbnail: "",
still: "",
embed: "<iframe src='http://api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/0717cc41-16c9-4122-ba0b-011ba581d2e8.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe>"
}
]
Creating media items is handled through our uploader component, please see the documentation for the uploader here
PUT /media/{media item id}.{format}
<mediaItem> <id>427b54f7-686f-45a0-984a-a717405e7672</id> <title>Nerdzilla defeats Geekazoid</title> <status>public</status> <description>Geeky robot fights with nerdy dinosaur and the dinosaur wins.<description /> <dateProduced>2008-12-01T16:36:00</dateProduced> <producer>kensei films</producer> <category>Portfolio<category /> <tags> <string>fun</string> <string>robot</string> <string>dinosaur</string> </tags> </mediaItem>
{
"id":"427b54f7-686f-45a0-984a-a717405e7672",
"title":"Nerdzilla defeats Geekazoid",
"type":"video",
"status":"public",
"description":"Geeky robot fights with nerdy dinosaur and the dinosaur wins",
"producer":"kensei films",
"dateProduced":"2008-12-01T16:36:00",
"category":"Portfolio",
"tags":[
"fun",
"robot",
"dinosaur"
],
}
Status: 200 OK
<mediaItem> <id>427b54f7-686f-45a0-984a-a717405e7672</id> <title>Nerdzilla defeats Geekazoid</title> <type>video</type> <status>public</status> <description>Geeky robot fights with nerdy dinosaur and the dinosaur wins.<description /> <dateCreated>2011-01-04T13:27:00</dateCreated> <userId>def41fc5-7298-439e-8cf4-22d9f3d374bd</userId> <username>bob_roperts</username> <originalFile>01111010101.mp4</originalFile> <producer>kensei films</producer> <dateProduced>2008-12-01T16:36:00</dateProduced> <duration>00:01:06</duration> <currentRating>4.76</currentRating> <totalViewed>137</totalViewed> <totalFavourites>12</totalFavourites> <category>Portfolio<category /> <tags> <string>fun</string> <string>robot</string> <string>dinosaur</string> </tags> <files> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4</url> <label>lo</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4</url> <label>hi</label> </mediafile> <mediafile> <url>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4</url> <label>hd</label> </mediafile> </files> <thumbnail>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</thumbnail> <still>http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg</still> <embed><iframe src='http://api.kenseimedia.com/V1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe></embed> </mediaItem>
Status: 200 OK
{
"id":"427b54f7-686f-45a0-984a-a717405e7672",
"title":"Nerdzilla defeats Geekazoid",
"type":"video",
"status":"public",
"description":"Geeky robot fights with nerdy dinosaur and the dinosaur wins",
"dateCreated":"2008-12-01T16:36:00",
"userId":"def41fc5-7298-439e-8cf4-22d9f3d374bd",
"username":"bob_roberts",
"originalFile":"01111010101.mp4",
"producer":"kensei films",
"dateProduced":"2008-12-01T16:36:00",
"duration":"00:01:06",
"currentRating":4.76,
"totalViewed":43,
"totalFavourites":12,
"category":"Portfolio",
"tags":[
"fun",
"robot",
"dinosaur"
],
"files":[
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.ipod.mp4",
"label":"lo"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.mp4",
"label":"hi"
},
{
"url":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672.hd.mp4",
"label":"hd"
}
],
"thumbnail":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1.jpg",
"still":"http://cdn.kenseimedia.com/14/v/h/o/427b54f7-686f-45a0-984a-a717405e7672/427b54f7-686f-45a0-984a-a717405e7672_1_m.jpg",
"embed":"<iframe src='http://api.kenseimedia.com/v1.1/1b86f38c-e62d-4142-b533-59e27df8ae0b/media/427b54f7-686f-45a0-984a-a717405e7672.embed' width='640' height='360' frameborder='0' allowfullscreen='true' webkitallowfullscreen='true' mozallowfullscreen='true'></iframe>"
}
DELETE /media/{media id}.{format}
Status: 200 OK
You can't currently get details about a single tag through the API. See List All to get tags for a library.
GET /tags.{format}
Status: 200 OK
<tags> <tag> <id>144542</id> <name>robots</name> </Tag> <Tag> <id>132001</id> <name>dinosaurs</name> </tag> </tags>
Status: 200 OK
[
{
"id": 144542,
"name": "Answers"
},
{
"id": 132001,
"name": "Odysseys"
}
]