The TwentyThree API
This document describes the REST API for Visualplatform, TwentyThree and Visualblog. Please note that access to the API depends on your product and subscription -- and that it may not be available to you. Contact us if you have questions in this regard.
This API is designed to be used in an array of different contexts: Browser- and JavaScript-based mashups with TwentyThree's products; customized video players in Adobe Flash or Adobe Flex; selecting and embedding content into a content management system; single sign-on or paywall-based access to TwentyThree; or full-fledged video or community sites using TwentyThree as their backend.
How are you planning to use the API?
The documentation details a number of different tools available for programmers. Depending on how you will be integrating against the API you likely will not be using all of the available bits and pieces − and for that reason it's important to ask how you will be using the API. In many cases, you won't need to worry about OAuth and access tokens.
A few examples:
Setting up a designed videosite with my own branding, my own content, on my own domain:
This is the core promise of TwentyThree, so you won't even need to use the API to achieve this goal. Consult Power Mode in Help Center for information on how to get started.
Re-using data from a public site to display thumbnails or embed videos:
In this case, you can skip OAuth entirely, an simply extract JSON or XML lists of content. Be sure to to understand response formats, pagination and the limitation of anonymous acess -- and then simply refer to the method documentation.
Using the TwentyThree site as a private archive for video:
Here, you will need OAuth signatures in order to sign requests to the API. You need to be confortable with the flow of OAuth, find a good OAuth library in your language of choice, and know the the API methods. You should create a set of privileged credentials from the backend of your site under Settings → API & Application to access the API.
Allowing user uploads to the TwentyThree site:
Again, you need OAuth signatures (see above), but you can use privileged credentials from Settings → API & Application in the site's backend. You have a choice between server-based or browser-based uploads, and you should understand the concept of pingbacks.
Having the user log in to their TwentyThree site site to grant you access:
This is the only case where you will need to worry about the OAuth authentication flow (since you can use privileged credentials otherwise). Along with everything else, you need to decide on a permission level to authenticate users at.
Giving visitors access to content through SSO or a paywall:
Users can be granted access through single sign-on which will grant them access to the content on an entire site. This aproach is designed to grant users full access to a site, it's content and the features afforded by the TwentyThree templating engine. Be sure to read the article on Single Sign-on Integration if you wish to know more.
As is clear from this list, the TwentyThree API can be used to achieve vastly different goals in different contexts. If you unsure on how to approach an integration, just ask us.
Terminology
For legacy reasons all TwentyThree APIs reference the object type photo
. However, depending on the service the API is used with, the photo
object type is interchangeable with text posts (on Visualblog), with photos (on Visualblog), and with videos (on TwentyThree and Visualblog).
The API or The TwentyThree API in this document refers to a set of methods made available on the TwentyThree platform in a well-defined manner and enabling programmers to retrieve data from and write data back to the system. The Client in the documentation can refer either to a browser, to the person using the browser, or generally to the program accessing the API.
The examples below refer to http://videos.examples.com
. In the real world, the domain should be replaced with the domain for the site you're querying.
Requests
The API is based on HTTP, and any request is made to the site's address (i.e. http://videos.examples.com
) followed by the API method name (i.e. /api/user/create
or /api/tag/related
).
Both GET and POST requests are allowed, but note that the GET-style query string parameters (i.e. /api/tag/related?tag=mytag
) are not used on POST requests.
For example, using the related tags method a request could look like this:
https://video.example.com/api/tag/related?tag=demo
And return something like this:
<response status="ok" permission_level="anonymous" total_count="2" cached="0"> <relatedtag tag="screencast" url="/tag/screencast"/> <relatedtag tag="video" url="/tag/video"/> </response>
The API expects UTF-8 formatted input and will return in UTF-8 as well.
The API is accessible via Adobe Flash and Adobe Flex. If you need to access it from a foreign domain, have a look at our cross-domain acces policies.
The next section describes how to authenticate your requests, and you should also have a look at the limits and possibilities of anonymous access to the api.
Authentication
The TwentyThree API uses the OAuth 1.0a protocol for user authorization and application identification.
Generally, some requests can be made anonymously, but whenever your application needs to read unpublished data or update or add new data, authentication is required. This is done by setting up consumer key
and a consumer secret
for you application, and then by having an existing user authorize your access. When this is done, you'll have an additional access token
and am access token secret
which will be used alongside your consumer credentials to sign all requests.
All interaction with the OAuth authentication process in done through a generic domain, http://api.visualplatform.net/oauth/*
, or through your site's own domain, http://videos.example.com/oauth/*
.
We encourage you to use the generic domain, since this will handle domain changes gracefully and will allow you to reuse code. Requests to http://api.visualplatform.net/oauth/access_token
will return the domain
to use for all subsequent requests to the API (more).
Request Token URL | http://api.visualplatform.net/... |
Access Token URL | http://api.visualplatform.net/... |
Authorize URL | http://api.visualplatform.net/... |
Signing mechanism | HMAC-SHA1 |
You can find more information on how to use OAuth 1.0a with the TwentyThree API in the OAuth set-up and flow document. Please refer to this document if you at all unsure about how to use OAuth with this API.
At first glance, the OAuth process might seem intimidating, but it has a major upside: It's used by Google, Yahoo, Twitter and tons of other services, which means that most web-programming languages already has one or more implementations to handle all necessary communication including both the authentication process and all request to the TwentyThree API. You can check out which libraries are available to you at the OAuth Code page.
We've also created a set of samples on how to authenticate your application and communicate with the TwentyThree API in PHP and Ruby.
Responses
By default responses from the API come in the form of a <response>
XML element (see response formats for more information). The root element will always have a status
attribute detailing if the request was ok
or error
. Both success and failure responses are returned with the HTTP status code 200.
Success
Successful requests will return XML formatted like this (or as JSON):
<response status="ok" message="The user exists"> <user_id>13579</user_id> <email>ernest@hemmingway.com</email> <username>ernest</username> <full_name>Ernest Hemmingway</full_name> <site_admin>1</site_admin> <timezone>Europe/Copenhagen</timezone> </response>
Failure
Whenever a request to the API fails, a response detailing the exception is returned. The response includes an error_code
and a detailed error description (see all error codes).
<response status="error" code="invalid_signature" message="The API signature is invalid."/>
Methods
Actions or calls-to-action
Methods for listing and managing calls-to-action overlay during video playback.
- /api/action/add: Add a call-to-action item.
- /api/action/delete: Delete a call-to-action item.
- /api/action/exclude: Exclude a call-to-action item for a specific object.
- /api/action/get: Get a list of action items.
- /api/action/update: Update a call-to-action-item.
- /api/action/upload: Upload a file for a an action variable.
Analytics reporting
Methods for creating and managing albums and channels.
- /api/analytics/report/event: Report an event to the analytics engine.
- /api/analytics/report/play: Report a playback to the analytics engine.
Albums or channels
Methods for creating and managing albums and channels.
- /api/album/create: Create a new channel or album
- /api/album/delete: Delete a channel or album
- /api/album/list: List and search through channels or albums
- /api/album/update: Update the meta data of a channel or album
Attachments
Methods for managing and querying video files attachments.
- /api/photo/attachment/list: Return a list of files attached to a video.
- /api/photo/attachment/upload: Upload attachments to a video.
Comments
Methods for listing and managing comments.
- /api/comment/add: Add a comment
- /api/comment/delete: Delete an existing comment
- /api/comment/list: List or search for comments
- /api/comment/promote: Promote or unpromote a comment.
Coordinates (or maps)
Methods for managing and listing geographic coordanates and maps associates with photos or videos.
- /api/photo/coordinate/add: Add a new geographic coordinate to a photo or video.
- /api/photo/coordinate/delete: Delete a geographic coordinate associated with a photo or video.
Edit
Methods for editing or trimming videos.
- /api/photo/edit/get-trimming: Get the current trimming information for a video.
- /api/photo/edit/set-trimming: Set the trimming information for a video, or create a duplicate.
Files or Design Files
Methods for listing and managing design files.
- /api/file/delete: Delete a design file.
- /api/file/list: List design files.
- /api/file/upload: Upload design file.
Licenses
Methods for listing and managing licenses.
- /api/license/list: List licenses.
Live
Methods for creating and managing live streams.
- /api/live/create: Create a new live stream.
- /api/live/delete: Delete a live stream.
- /api/live/get-program-date: Get the current absolutely time of a part of the live stream.
- /api/live/list: List one or more live streams.
- /api/live/list-formats: List live event formats.
- /api/live/log: Pull a list of actions that happened on the live stream.
- /api/live/reset-token: Reset token for a live event.
- /api/live/update: update a live stream.
- /api/live/upload-image: Upload a thumbnail or a preview image for the stream.
Live schedule
Methods for working with the schedule for live streams
- /api/live/schedule/add: Add a time to the streaming schedule.
- /api/live/schedule/list: List the upcoming streaming schedule.
- /api/live/schedule/remove: Remove a time from the streaming schedule.
- /api/live/schedule/update: Update a schedule item.
Live recording
Methods for recording from live streams.
- /api/live/recording/start: Start recording a video stream.
- /api/live/recording/status: Status on current recording.
- /api/live/recording/stop: Stop recording a video stream.
Audience
Methods for managing listing viewer profiles and viewing timelines. To sync data with Audience, refer to the webhooks documentation in the TwentyThree Help Center.
- /api/audience/list: List viewer profiles including timeline activities and conversion events.
- /api/audience/metrics: Get aggregate metrics for a set of profiles.
Photos and videos
Methods for uploading and managing videos and photos.
- /api/photo/delete: Delete a photo or video.
- /api/photo/frame: Extract a single frame of a video clip as a JPEG image.
- /api/photo/get-ratings: Get a list of photo ratings.
- /api/photo/get-replace-token: Get a token for browser-based and non-authenticated replace of photos, thumbnails and videos.
- /api/photo/get-transcoding-progress: Get the transcoding progress of a specific video.
- /api/photo/get-update-token: Get a token for changing meta data.
- /api/photo/get-upload-token: Get a token for browser-based and non-authenticated uploading.
- /api/photo/list: List and search through photos and videos.
- /api/photo/rate: Rate a photo or video.
- /api/photo/redeem-replace-token: Replace a video, thumbnail or photo using a replace token.
- /api/photo/redeem-update-token: Update meta data using an update token.
- /api/photo/redeem-upload-token: Upload a video or photo using an upload token.
- /api/photo/replace: Replace a photo, replace a video or update the thumbnail of a video.
- /api/photo/reset-token: Reset token for video or photo.
- /api/photo/update: Update the meta data of a photo or video.
- /api/photo/update-upload-token: Update the meta data of a photo or video, which has previously been or is in the process of being uploaded to the site through browser-based uploading.
- /api/photo/upload: Upload a new photo or video.
Protection
Methods for managing listing viewer profiles and viewing timelines. To sync data with Audience, refer to the webhooks documentation in the TwentyThree Help Center.
- /api/protection/protect: Protect a video or stream.
- /api/protection/unprotect: Unprotect a video or stream.
- /api/protection/verify: Verify access to a video or stream.
Players
Methods for listing and use video players.
- /api/player/embed: Get a player embed code
- /api/player/list: List available video players
- /api/player/settings: Request specific player settings
Sections
Methods for managing and listing sections or chapters within video clips.
- /api/photo/section/create: Create a section within a video.
- /api/photo/section/delete: Delete a video section.
- /api/photo/section/list: List sections within a video.
- /api/photo/section/set-thumbnail: Set the thumbnail for a specified section within a video.
- /api/photo/section/update: Update a section within a video.
Sessions
Methods controlling access to a closed site and for implementing single sign-on. Be sure to read the guide to Single Sign-On integration to see how these methods can be used to grant users access.
- /api/session/get-token: Get a token for authorizing a visitor's access to a site.
- /api/session/redeem-token: Get access to a site through a session token.
Setting
Methods for managing account settings.
- /api/setting/list: List account settings.
- /api/setting/update: Update one or more account settings.
- /api/setting/list-ip-ranges: List whitelisted IP ranges for the account.
- /api/setting/add-ip-ranges: Add one or more IP ranges to white-list for the account.
- /api/setting/remove-ip-ranges: Remove one or all ip ranges from an account.
Site
Methods for querying meta data about sites.
- /api/site/get: Get information about the site.
- /api/site/search: Search objects on site.
Spots and Landing Pages
Methods for working with spot and landing pages.
- /api/spot/list: List spots and landing pages.
- /api/spot/create: Create a new spot or landing page.
- /api/spot/update: Update a spot or landing page.
- /api/spot/delete: Delete a spot or landing page.
- /api/spot/set-videos: Set which videos are displayed within a spot or landing page -- and in which position.
Subtitles
Methods for managing and querying video subtitles and captions.
- /api/photo/subtitle/data: Return the raw data (usually in JSON or WebSRT) to show subtitles.
- /api/photo/subtitle/list: Retrieve subtitles for a video.
- /api/photo/subtitle/remove: Remove subtitles.
- /api/photo/subtitle/upload: Upload subtitles.
Tags
Methods for searching tags.
- /api/tag/list: List or search through tags
- /api/tag/related: List related tags
Testing
Methods for testing communication with the API
- /api/echo: Mirrors parameters in return
Users
Methods for managing users.
- /api/user/create: Create a new user account
- /api/user/get-login-token: Get a token for logging in a user.
- /api/user/list: List users
- /api/user/redeem-login-token: Log in a user using a login token.
- /api/user/update: Update a user account
Utility
Utility methods for the platform.
- /api/utility/geography: Detect geopgraphical location from IP.
- /api/utility/video-capabilities: List mobile capabilities.
- /api/utility/help: Search the TwentyThree Help Center and the API documentation.
Webhooks
Subscribe to and manage webhooks from TwentyThree.
- /api/webhook/events: List available webhook events.
- /api/webhook/list: List current webhook subscriptions for the client.
- /api/webhook/subscribe: Subscribe to a webhook.
- /api/webhook/unsubscribe: Unsubscribe to a webhook.
Response formats
The API response is available in two formats: XML and JSON. By default, the API will respond in XML, but you can force the format using the format parameter:
http://videos.example.com/api/tag/list?format=xml / http://videos.example.com/api/tag/list?format=json
Detailed above the XML responses will be wrapped in a <response>
root node with a number of attributes (such as status
, permission_level
and cached
) describing the returned data. The content of the root node varies depending on the method invoked and is described in the individual method documentation.
The JSON return format will return the same data as the XML format, but it will be formatted differently and the response will also include information about the site being queried. A request to http://videos.example.com/api/tag/list?size=2&format=json
might yield:
var visual = { "status": "ok", "permission_level":"read", "cached":"0", "tags":[ {"tag": "23", "count": "4", "url": "/tag/23"}, {"tag": "3gpp", "count": "1", "url": "/tag/3gpp"} ], "p": "1", "size": "2", "total_count": "69", "site": { "domain": "videos.example.com", "product_key": "tube", "site_id": "123456", "site_name": "Example Video Site" }, "endpoint": "/api/tag/list"}
As you can see, the site
object contains the name, id and product identifier of your site.
The variable name can be controlled by setting varname
. For example, requesting http://videos.example.com/api/tag/list?format=json&varname=tags
would return:
var tags = { "status": "ok", tags:[...] ...}
The response is also available as a JSONP-style callback using the callback
parameter. Requesting the same data with http://videos.example.com/api/tag/list?format=json&callback=updateTags
gets you:
updateTags({ "status": "ok", tags:[...] ...})
This is valuable for cross-domain scripting in a browser:
<script> function updateTags(o) { for (i in o.tags) { doEvilStuffWithTag(o.tags[i].tag); } }</script><script src="http://videos.example.com/api/tag/list?format=json&callback=updateTags"></script>
Finally, you can get raw JSON data without any unnecessary syntactic sugar using raw
. Asking for http://videos.example.com/api/tag/list?format=json&raw
would answer:
{ "status": "ok", tags:[...] ...}
Pagination
A number of API methods (including for example /api/photo/list, /api/user/list and /api/tag/list) returns a list of objects. These lists will often only return a subset of the data, and the programmer will need to handle pagination explicitly. This is done using p
and size
:
size
: Number of items to return with each request. Where nothing else is stated, the default value forsize
is 20 and the maximum value is 100.p
: The page number to return. The default value is 1 and given a size of 20,p=2
will return items 21 through 40, andp=5
will yield items 81 through 100.
Any request offering pagination will include the p
and size
parameters in their responses, and in addition a third property is included:
total_count
: The total number of object available through the request.
For example, you might query http://videos.example.com/api/tag/list
:
<response status="ok" permission_level="anonymous" p="1" size="20" total_count="69" cached="0"> ( ... 20 tag objects ... )</response>
Based on the response, we know that there are 69 tags distributed along ceil(69/20) = 4 pages. Armed with this information we can make a few additional requests ending with http://videos.example.com/api/tag/list?size=20&p=4
:
<response status="ok" permission_level="anonymous" p="4" size="20" total_count="69" cached="0"> ( ... 9 tag objects ... )</response>
Anonymous access
A number of the API methods allow anonymous access to the public data from public sites. For example, a request to http://videos.example.com/api/... will yield a list of published videos of the site including information on how to play and embed these videos.
Of course, unpublished content on public sites and any content on non-public sites will not be available to anonymous API calls. For more information about access and permission levels, refer to the next section.
Token access to photos and videos
In general terms, access to photos and videos can be controlled through an identifier (photo_id
) and a shared secret (token
). Using a combination of these two, you will always be able to retrieve the full URL of an object. This method can be used to grant access to unpublished or hidden videos to select users, for example through an embed code.
- On publicly accessible sites, both the
photo_id
andtoken
of any published photo or video is freely available through the API. - On closed sites,
token
s on published videos are available to visitors with their sessions signed. - All
token
s (including those to non-published videos) are available to logged-in users. This also means that thetoken
for unpublished items is not available to the public without it having been explicitly shared.
Put plainly: If a token
is shared, a user will always have access to an item. When a video is made public, the token is too.
Access protection on streams
The platform and API provides full protection scheme for securing access to videos, for example with passwords, geographic location, paywalls or even through third-party services. This builds on top of the id
+ token
method described above and is covered in detail in Protecting videos and streams.
Permission levels
The API operates with a set of different permission levels. At each level, some actions are allowed and some are prohibited:
- Permission level
none
: You are given no access to the API. At this level, you will need specific information such as album_id or photo_id plus a secret token to access data. This level is usually only applied when a sites is closed to the public and the client hasn't been authenticated in any way. - Permission level
anonymous
: The client has access to publicly available data. The is the default access level on a public site. On a non-public site, the permission level is only given to clients logged in through the standard cookie login mechanism (which isn't part of the API). - Permission level
read
: Access at this level can be granted through the OAuth authentication process. At this level, both public and private data is available through the API. - Permission level
write
: Access at this level can be granted through the OAuth authentication process and will allow the API to both add new objects (i.e. uploading video) and delete existing ones. - Permission level
admin
: Access at this level can be granted through the OAuth authentication process and will allow the API to perform administration actions such as creating new users. - Permission level
super
: Access at this level can only be obtained by keys and tokens created by the site owner setting up privileged credentials in a site's backend. Using these credentials, the API will be able to log in users and sign client sessions.
The levels are listed in ascending order, meaning that super
authentication will give access to all lesser levels as well, and a client with read
will also have anonymous
and none
rights.
How these rules are applied to methods is detailed under the individual method documentation. Whenever a request is denied due to lack of permissions, an error message is return detailing both the client's actual level and the level necessary:
<response status="error" permission_level="none" code="permission_denied" message="You don't have the necessary permissions to perform this action (required level: 'admin')"/> ...</response>
Or in JSON speak:
{ "status": "error", "message": "You don't have the necessary permissions to perform this action (required level: 'admin')", "code": "permission_denied", "permission_level": "none", "endpoint": "/api/user/create" }
Any request to the API will also list the client's permission level in the response attributes. For example:
<response status="ok" permission_level="read" p="1" size="20" total_count="16" cached="0">
Caching
Anonymous requests to the API are subject to caching. This means that responses can be cached for a period of up to 30 minutes. Signed requests to the API are never cached.
Cached responses will have cached=1
set in the response. For example in XML responses:
<response status="ok" p="1" size="20" total_count="1" cached="1" cache_time="1266304557"> ...</response>
Or in the JSON response:
{ "status": "ok", "cached":"1", "cache_time":"1266304557", ....}
The extra property cache_time
notes when the content of the response was originally cached in seconds since epoch. For example, these responses were originally cached on February 16th 2010 at 08:15am.
For performance reasons, we ask you to use the cached version of any request, but you will be able to ask for a non-cached version of a response either by signing your requests or by adding a ?time=<current_timestamp>
parameter to your request.
Pingbacks
You can have the API notify you of object changes on TwentyThree through pingback notifications. This is done by configuring you OAuth consumer with a Pingback URL
. A common usage for this approach is to both listen for new uploads to a site and to track the transcoding of an uploaded video.
For example, you might use http://backend.example.com/visual-pingback
and whenever a photo's or video's title, description, tags, albums, channels or encoding status changes, a HTTP POST request is sent back to the specified URL:
<pre><code><a href=" Using">http://backend.example.com/vis... this information, you will be able to track changes in the TwentyThree backend. The pingback itself only identifies the changed object; you will need to query /api/photo/list for updated information about the object.
Only photo
objects are subject to pingback notifications.
Browser-based uploads
Browser-based uploading is designed to allow API consumers to pre-authenticate uploads to their TwentyThree sites -- and enables applications to let users upload photos and videos to TwentyThree using browser-based uploading. This scheme allows you to accept uploads from users without ever having to proxy or host the files from you server. You should opt for this approach to uploading if you do not want to host or store the uploaded files.
The entire flow is detailed and exemplified in Using browser-based with TwentyThree.
Thumbnails
Thumbnails and preview images for videos and live streams can be set up in different sizes when logged in to a TwentyThree website as an administrator. The urls to thumbnails and preview images can be read from the ´photo´ and ´live´ objects returned from /api/photo/list and /api/live/list, respectively.
The size of a requested image can also be specified directly in the url. For example, to get a 600px wide and 400px high version of a video's thumbnail, the url would be constructed like so, where ´tree_id´, ´photo_id´ and ´token´ are properties available on the ´photo´ object:
http://video.example.com/<tree_id>/<photo_id>/<token>/600x400/thumbnail.jpg
Read the full documentation on thumbnails.
Libraries and sample implementations
The TwentyThree API is designed to be generic and accessible in just about any programming language. We are making a number of implementations and libraries available to make the interaction easier:
- .NET API for TwentyThree
- Client-side JavaScript library the TwentyThree
- Node.js library for TwentyThree
- PHP sample implementation
- Ruby sample implementation
- SharePoint Web Part for 23 Video
- All sample scripts
Any questions?
As noted in the beginning of this document, the TwentyThree API is designed to be used in a multitude of different contexts. If you find it comes up short and have suggestions for improvements -- or if you have questions on how to use the API -- feel free to reach out to us on support@twentythree.com