CDN API Documentation

From Sirikata Wiki
Jump to: navigation, search

Model URLs

The URL for a model consists of:



  • BASENAME = The user-chosen path for the model, e.g. /jterrace/duck.dae
  • HOSTNAME = Address of the CDN server. If not specified, the OH client defaults to
  • FORMAT = One of the CDN formats. Currently supported are "priginal", "pptimized" and "progressive".
  • VERSION = The version number of the model. If not specified, the latest version is returned by the CDN.


  • Returns the latest version of optimized format:
  • Returns progressive format, version 0:
  • Loads from a server on localhost:


The filename at the end of the URL is technically optional, but the OH won't pick up dependent files, like textures, without it.

Retrieving Single Model Info


This retrieves the JSON for a single model with all of its formats.


Browsing the CDN


This browses the models on the CDN. Without a start argument, returns the most recent 25 models on the CDN. It will also contain a "next_start" value, which you can pass later to start at the next timestamp to continue browsing.


Searching the CDN


This searches the CDN for models matching the query QUERY.


  • q (optional) - something to search for (ex: duck). If not specified, the search returns all models.
  • start (optional) - an index value to continue searching from. Defaults to 0.
  • rows (optional) - how many rows to return. Defaults to 10. Maximum value of 100.


Return value is JSON. Contains 4 keys:

  • content_items - same as /api/browse
  • hits - the total number of models on the CDN matching the query
  • next_start - the index value to pass as "start" parameter to continue where the query left off
  • previous_start - the index value to go backwards in search results




This requires authentication using OAuth. Only an access token is required, and you can get that from a user's profile page on the CDN site.


  • title - The title of the model
  • username - The username that is being used to upload. This must match the username of the OAuth key.
  • path - Where to place the file, relative to the user's path. For example, if username is jterrace and path is "test/duck.dae", the final path will be "/jterrace/test/duck.dae"
  • main_filename - If uploading multiple files, this should be the main file (e.g. COLLADA). This is still required even if only a single file is being uploaded. If you upload a zip file, this should be the name of the zip file.
  • description - Description for the model
  • labels - Any labels you want on the model
  • ephemeral - Set to '1' if this is an ephemeral upload
  • ttl_time - (ephemeral only) The time to live for an ephemeral upload.
  • subfiles - (ephemeral only) A json-encoded dictionary mapping textures to existing texture paths on the CDN. Example:
   {"duckCM.tga": "/jterrace/duck_triangulate.dae/original/duckCM.tga/0"}

The keys are always the bare filename. For example, even if the file is listed as '/home/jterrace/duck/duckCM.tga' in the model, the key will be 'duckCM.tga'.

The actual files should be multipart encoded.


If successfull, the HTTP code should be 200. The reponse will be a JSON string. There will be a field named 'success' set to True. If an application-level error happened, there will be a field named 'error' that contains a human-readable string with the error in it. On success, a field name 'task_id' will contain the upload task identifier (used later to get the status of the upload).

Upload Status


This allows you to get the status of an upload. The TASK_ID should be the 'task_id' string returned from /api/upload. The username should be the username used to upload the file. The returned value will be a JSON string. There will be a field called 'state'. When the value of this field is either SUCCESS or FAILURE, it means the upload process has completed. Otherwise, a human-friendly status code will be returned indicating what stage the import is in. If the state is FAILURE, it means the upload has failed. If the state is SUCCESS, an additional field named 'path' will contain the new path of the file that has been imported. Once SUCCESS or FAILURE has been returned, the given TASK_ID is no longer a valid argument for this URL, e.g. you can only consume it once.

Keepalive Update


This requires authentication using OAuth.

This allows updating the TTL value for ephemeral uploads.


  • ttl - TTL time to update to
  • username - The username this model belongs to


An empty 200 response on success.