Skip to Content

TwentyThree

TwentyThree™ API

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.

Analytics reporting

Methods for creating and managing albums and channels.

Albums or channels

Methods for creating and managing albums and channels.

Attachments

Methods for managing and querying video files attachments.

Comments

Methods for listing and managing comments.

Coordinates (or maps)

Methods for managing and listing geographic coordanates and maps associates with photos or videos.

Edit

Methods for editing or trimming videos.

Files or Design Files

Methods for listing and managing design files.

Licenses

Methods for listing and managing licenses.

Live

Methods for creating and managing live streams.

Live schedule

Methods for working with the schedule for live streams

Live recording

Methods for recording from live streams.

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.

Photos and videos

Methods for uploading and managing videos and photos.

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.

Players

Methods for listing and use video players.

Sections

Methods for managing and listing sections or chapters within video clips.

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.

Setting

Methods for managing account settings.

Site

Methods for querying meta data about sites.

Spots and Landing Pages

Methods for working with spot and landing pages.

Subtitles

Methods for managing and querying video subtitles and captions.

Tags

Methods for searching tags.

Testing

Methods for testing communication with the API

Users

Methods for managing users.

Utility

Utility methods for the platform.

Webhooks

Subscribe to and manage webhooks from TwentyThree.

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 for size 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, and p=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 and token of any published photo or video is freely available through the API.
  • On closed sites, tokens on published videos are available to visitors with their sessions signed.
  • All tokens (including those to non-published videos) are available to logged-in users. This also means that the token 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:

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