Developers

Cloudup API

Welcome to the Cloudup API documentation.

All end-points accepting a body must be application/json or application/x-www-form-urlencoded, and all responses are application/json. All requests must be made over HTTPS, and are otherwise rejected.

Versioning

All requests in this documentation are made over HTTPS to the following URL, where 1 represents version 1.0 of the Cloudup API.

https://api.cloudup.com/1

Backwards-incompatible changes made to the API will result in a version bump.

Authentication

Cloudup API 1.0 supports two methods of authentication, Basic Auth, and Oauth 2.0. In order to utilize OAuth authentication you must first have a Cloudup account, and register your application in your user settings.

Cloudup's OAuth authorization end-point is https://cloudup.com/oauth/authorize, and access token end-point is https://cloudup.com/oauth/access_token.

Pagination

Most Cloudup resources are paginated, responding with 30 objects per request. When the number of objects exceeds 30, a Link header field is provided with one or both "next" and "prev" links. For example:

GET /streams?page=2
HTTP/1.1 200 OK
Link: <https://cloudup.com/streams?page=1>; rel="prev",
      <https://cloudup.com/streams?page=3>; rel="next"
      

In addition a X-Total header field is included in all paginated responses, providing the total number of objects as shown here:

GET /streams
X-Total: 66

Rate Limiting

Requests are limited to 2500 per hour. The X-RateLimit-Reset header field indicates the number of seconds until the rate-limiter will reset. When exceeded a 429 "Too Many Requests" status code is returned.

GET /streams
HTTP/1.1 200 OK
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2453
X-RateLimit-Reset: 1375308561

Filtering responses

Most Cloudup API calls support response filtering, this mechanism allows you to choose what we respond with to increase performance when you only need a subset of the data.

This is achieved wit the ?only query-string parameter, which is given a comma-separated list of properties as shown here:

GET /items?only=id,title
[
  {
    "id": "isdb0iFZN00",
    "title": "Ferrets"
  },
  {
    "id": "i-gWhBaurGh",
    "title": "Watch"
  },
  {
    "id": "i1v5q3COFwD",
    "title": "Watch"
  }
...

oEmbed

Cloudup supports oEmbed, a small JSON API for embedding content in your application. No authentication is required for oEmbed, you may simply pass an item or stream url to the /oauth end-point

GET /oembed?url=https://cloudup.com/cJCjWBYGhWb
{
  "version": "1.0",
  "type": "rich",
  "title": "Swan Lake",
  "url": "https://cloudup.com/cJCjWBYGhWb",
  "provider_name": "Cloudup",
  "provider_url": "https://cloudup.com",
  "thumbnail_url": "https://cloudup.com/collage/cJCjWBYGhWb", 
  "thumbnail_width": 600, 
  "thumbnail_height": 438
}

Streams

Cloudup "Streams" contain zero or more "Items", and may be modified at any time by adding, removing, or re-ordering items. The Cloudup API provides the ability to list, create, update, and delete streams.

Schema

The Stream schema is as follows, describing the information available to you as a developer, and the requirements when updating a Stream.

NameDescriptionType
idunique stream identifierstring
titlestream titlestring
creator_idstream owner's identifierstring
created_atstream creation datedate
updated_atstream update datedate
itemsitems in the streamarray
urlcloudup stream urlstring

Get a stream

To fetch information about a stream issue a GET request with its :id.

GET /streams/cwUdV5rv1rT
{
  "id": "cwUdV5rv1rT",
  "title": "Photos",
  "creator_id": "519d7e25adaa11b598c58dba",
  "created_at": "2013-06-13T17:19:37.677Z",
  "items": [
    "iy9db9wUroy",
    "icZCMwsbIGm",
    "i_5B4xtxDhC"
  ]
}

Create a stream

To create a Stream issue a POST to /streams. No properties are required to create a stream.

POST /streams -d 'title=Ferrets'

Update a stream

To update information about a stream issue a PATCH request with its :id.

PATCH /streams/cwUdV5rv1rT -d 'title=Ferrets'

Delete a stream

To delete a stream issue a DELETE request with its :id.

DELETE /streams/cwUdV5rv1rT

Get all streams

To get a paginated list of streams issue a GET to /streams, and use the Link header field to navigate between the pages. The X-Total header field contains the total number of streams.

GET /streams
[
  {
    "id": "cAAETb9SGgY",
    "title": "Wallpaper",
    "creator_id": "519d7e25adaa11b598c58dba",
    "created_at": "2013-05-30T21:46:47.724Z",
    "updated_at": "2013-05-30T21:47:52.023Z",
    "items": [
      "igKwICGXjyd"
    ]
  },
  {
    "id": "cyM53xYzuZs",
    "title": "Ferrets",
    "creator_id": "519d7e25adaa11b598c58dba",
    "created_at": "2013-05-23T16:27:20.865Z",
    "updated_at": "2013-05-23T16:27:20.865Z",
    "items": [
      "iqd2t9X-Pdt"
    ]
  },
...

Get stream items

To get a paginated list of streams items, issue a GET to /streams/:id/items, and use the Link header field to navigate between the pages. The X-Total header field contains the total number of items.

GET /streams/cwUdV5rv1ra/items
[
  {
    "id": "iE5DaEUKQYd",
    "title": "Console",
    "stream_id": "cc3pGD6avN7",
    "type": "code",
    "filename": "console.js",
    "progress": 100,
    "url": "https://cloudup.com/iE5DaEUKQYd",
    "direct_url": "http://i.cloudup.com/thuMetFy8N.js",
    "mime": "application/javascript",
    "thumbs": [],
    "creator_id": "51f6e65627281d351c744405",
    "created_at": "2013-07-31T21:09:09.751Z",
    "progress_at": "2013-07-31T21:09:10.010Z",
    "completed_at": "2013-07-31T21:09:10.238Z",
    "complete": true
  },
  {
    "id": "iFVvNJbHOHA",
    "title": "Plain",
    "stream_id": "cc3pGD6avN7",
    "type": "code",
    "filename": "plain.js",
    "progress": 100,
    "url": "https://cloudup.com/iFVvNJbHOHA",
    "direct_url": "http://i.cloudup.com/ja1vECdvok.js",
    "mime": "application/javascript",
    "thumbs": [],
    "creator_id": "51f6e65627281d351c744405",
    "created_at": "2013-07-31T21:09:09.721Z",
    "progress_at": "2013-07-31T21:09:09.930Z",
    "completed_at": "2013-07-31T21:09:10.178Z",
    "complete": true
  }
...

Items

Cloudup "Items" may be files or website urls and may exist within a single "Stream". The Cloudup API provides the ability to list, create, update, and delete items.

Schema

The Item schema is as follows, describing the information available to you as a developer, and the requirements when updating a Item.

NameDescriptionType
idunique item identifierstring
titleitem titlestring
stream_idassociated stream idstring
typeitem type: code, file, embed, url, article, unknownstring
filenameitem filenamestring
sizefile size in bytesnumber
progressitem upload progressnumber
urlcloudup item urlstring
direct_urlurl of the original item uploadstring
mimeitem mime typestring
widthitem image widthnumber
heightitem image heightnumber
exifEXIF tagsobject
thumbsitem thumbnailsobject
thumb_urlinitial item thumbnailstring
thumbthumbnail filenamestring
thumb_widthitem thumbnail image widthnumber
thumb_heightitem thumbnail image heightnumber
transcode_statevideo transcoding job state: submitted, progressing, complete, canceled, errorstring
transcode_urlurl of the transcoded video filestring
htmlhtml representationstring
html_thumbhtml 'thumbnail' snippetstring
creator_iditem owner's identifierstring
created_atitem creation datedate
progress_atitem progress update datedate
completed_atitem upload completion datedate
completeitem upload success flagboolean
s3_keys3 object upload keystring
s3_policys3 serialized policy for request usagestring
s3_signatures3 policy signature for request usagestring
s3_urls3 url for issuing the POST requeststring
s3_access_keys3 access key for request usagestring
oembed_urloembed urlstring
oembed_htmloembed htmlstring
oembed_typeoembed typestring
oembed_widthoembed widthnumber
oembed_heightoembed heightnumber
oembed_thumbnail_urloembed thumbnail urlstring
oembed_provider_nameoembed providerstring

Get an item

To fetch information about an item issue a GET request with its :id.

GET /items/iBH4OVcMOeW
{
  "id": "iBH4OVcMOeW",
  "title": "Tobi",
  "stream_id": "cc3pGD6avN7",
  "type": "file",
  "filename": "tobi.jpg",
  "url": "https://cloudup.com/iBH4OVcMOeW",
  "direct_url": "http://i.cloudup.com/YQctM0kuUw.jpg",
  "mime": "image/jpeg",
  "thumbs": [],
  "creator_id": "51f6e65627281d351c744405",
  "created_at": "2013-07-31T22:34:32.775Z"
}

Create a file item

To create an Item associated with a file issue a POST to /items. Only the filename property is required. The item may be associated with a stream later via a PATCH request, however you may include the stream_id as shown in the following example:

POST /items -d 'filename=tobi.jpg&title=Tobi&stream_id=cc3pGD6avN7'
{
  "id": "io5mDaTEytP",
  "title": "Tobi",
  "type": "file",
  "filename": "tobi.jpg",
  "stream_id": "cc3pGD6avN7",
  "url": "https://cloudup.com/io5mDaTEytP",
  "direct_url": "http://i.cloudup.com/udMfm2Dab0M/IUsvM3.jpg",
  "mime": "image/jpeg",
  "thumbs": [],
  "creator_id": "udMfm2Dab0M",
  "created_at": "2013-08-21T17:18:33.099Z",
  "s3_key": "udMfm2Dab0M/IUsvM3.jpg",
  "s3_policy": "eyJleHBpcmF0aW9uIjoiMjAxMy0wOC0yMlQxNzoxODozMy4xMDRaIiwiY29uZGl0aW9ucyI6W1sic3RhcnRzLXdpdGgiLCIka2V5IiwidWRNZm0yRGFiME0vSVVzdk0zLmpwZyJdLFsic3RhcnRzLXdpdGgiLCIkQ29udGVudC1UeXBlIiwiIl0sWyJzdGFydHMtd2l0aCIsIiRDb250ZW50LUxlbmd0aCIsIiJdLFsiY29udGVudC1sZW5ndGgtcmFuZ2UiLDEsMjA5NzE1MjAwXSx7ImJ1Y2tldCI6ImkuY2xvdWR1cC5jb20ifSx7ImFjbCI6InB1YmxpYy1yZWFkIn1dfQ==",
  "s3_signature": "EQB6pI67CZiKEHEcAl8Bs0Mp6eA=",
  "s3_url": "http://i.cloudup.com.s3.amazonaws.com",
  "s3_access_key": "AKIAJ7R3QQCY37AQ5HNQ"
}

Uploading the file

The POST response includes several .s3_* properties which may be used to upload the file directly to s3 using a multipart/form-data request. For a working sample view the CORS example.

Upload progress

While not required, it is strongly recommended that you send PATCH requests periodicaly to update the .progress of an item's upload. Once the upload is complete you MUST send a PATCH request to the item with { complete: true } to finalize the upload.

Thumbnails

Cloudup generates thumbnails for content automatically, however for the end-users it is often appropriate to send a reasonably small thumbnail ahead of time to improve the experience. If a thumbnail is omitted viewers will not receive a thumbnail until the file is successfully uploaded to s3 and processed by our system.

The s3 upload process is identical, however the s3 "key" (the object name) should be the original key with ".thumb.jpg" or ".thumb.png" appended. For example the s3_key of udMfm2Dab0M/IUsvM3.jpg with a jpeg thumbnail would become udMfm2Dab0M/IUsvM3.jpg.thumb.jpg.

Once a thumbnail upload is complete you MUST send a PATCH request to the item with thumb to indicate that a thumb has been uploaded. The value of thumb should be the newly created s3_key, for example: { thumb: 'udMfm2Dab0M/IUsvM3.jpg.thumb.jpg' }.

Create a url item

To create an Item associated with a URL issue a POST to /items/url. Only the url property is required. The item may be associated with a stream later via a PATCH request, however you may include the stream_id as shown in the following example:

POST /items/url -d 'url=cloudup.com&stream_id=cc3pGD6avN7'
{
  "id": "idMcEraILYl",
  "title": "Cloudup",
  "stream_id": "cc3pGD6avN7",
  "url": "https://cloudup.com/idMcEraILYl",
  "direct_url": "http://cloudup.com",
  "mime": "text/html",
  "thumbs": [],
  "creator_id": "51fbdf3c550ae548b430734e",
  "created_at": "2013-08-16T21:54:51.665Z"
}

Embeds

Cloudup supports "embeds", urls that provide rich content such as audio or video players, which may be embedded directly in your stream. The following example is the response from a YouTube video:

POST /item/url -d 'url=http://www.youtube.com/watch?v=_JhZlhrwano'
{
  "id": "itHyKgjyNRM",
  "title": "Cloudup",
  "type": "embed",
  "url": "https://cloudup.com/itHyKgjyNRM",
  "direct_url": "http://www.youtube.com/watch?v=_JhZlhrwano",
  "mime": "text/html",
  "thumbs": [],
  "creator_id": "51fbdf3c550ae548b430734e",
  "created_at": "2013-08-16T21:57:48.854Z"
}

As this process is async, subsequent requests will expose additional information such as screenshot thumbnails and embed meta-data:

GET /items/itHyKgjyNRM
{
  "id": "itHyKgjyNRM",
  "title": "Cloudup",
  "stream_id": "cc3pGD6avN7",
  "type": "embed",
  "url": "https://cloudup.com/itHyKgjyNRM",
  "mime": "text/html",
  "thumbs": [],
  "creator_id": "51fbdf3c550ae548b430734e",
  "created_at": "2013-08-16T21:57:48.854Z",
  "complete": true,
  "oembed_url": "http://www.youtube.com/watch?v=_JhZlhrwano",
  "oembed_html": "<iframe width=\"854\" height=\"480\" src=\"https://www.youtube.com/embed/_JhZlhrwano?feature=oembed\" frameborder=\"0\" allowfullscreen></iframe>",
  "oembed_type": "video",
  "oembed_width": 854,
  "oembed_height": 480,
  "oembed_thumbnail_url": "http://cdn.sslreque.st/eaa357a12c8fdcb513efeb5a63755f87f474172e/687474703a2f2f69312e7974696d672e636f6d2f76692f5f4a685a6c687277616e6f2f687164656661756c742e6a7067?32489955",
  "oembed_provider_name": "YouTube"
}

Files

Cloudup supports remote file uploads via URLs. When you POST a URL which points to a file it is fetched and stored within our system for safe keeping. For example posting http://www.lua.org/doc/jucs05.pdf will result in the following item:

{
  "id": "iB8TKvvp4KK",
  "title": "Jucs05",
  "stream_id": null,
  "type": "file",
  "filename": "jucs05.pdf",
  "size": 148160,
  "progress": 100,
  "url": "https://cloudup.com/iB8TKvvp4KK",
  "direct_url": "http://i.cloudup.com/iNZpuMmCbky.pdf",
  "mime": "application/pdf",
  "exif": {
    "exiftool version number": "9.08",
    "file name": "Uv0SahoYH8",
    "directory": "/tmp/thumbs",
    "file size": "145 kB",
    "file modification date time": "2013:08:16 22:10:05+00:00",
    "file access date time": "2013:08:16 22:10:05+00:00",
    "file inode change date time": "2013:08:16 22:10:05+00:00",
    "file permissions": "rw-rw-r--",
    "file type": "PDF",
    "mime type": "application/pdf",
    "pdf version": "1.2",
    "linearized": "No",
    "page count": "18",
    "producer": "GNU Ghostscript 7.07",
    "orientation": null
  },
  "thumbs": [
    {
      "size": {
        "string": "300x300",
        "width": 300,
        "height": 300
      },
      "width": 212,
      "height": 300,
      "format": "jpeg",
      "orientation": {},
      "url": "http://i.cloudup.com/PHjxbDZF4f-300x300.jpeg"
    }
    ...
  ],
  "creator_id": "51fbdf3c550ae548b430734e",
  "created_at": "2013-08-16T22:10:00.772Z",
  "complete": true
} 

Update an item

To update information about an item issue a PATCH request with its :id.

PATCH /items/iiT8AlF0HgU 'progress=50'

While an upload is in progress it is recommended that you periodically update the progress property. Once complete you must set complete to true.

Delete an item

To delete an item issue a DELETE request with its :id.

DELETE /items/iBH4OVcMOeW

Get all items

To get a paginated list of items issue a GET to /items, and use the Link header field to navigate between the pages. The X-Total header field contains the total number of streams.

GET /items?only=id,stream_id,title,filename
[
  {
    "id": "iiT8AlF0HgU",
    "title": "Console",
    "stream_id": "cAPNkCR8mMp",
    "filename": "console.js",
    "url": "https://cloudup.com/iiT8AlF0HgU"
  },
  {
    "id": "iMQTrKyW7y5",
    "title": "Console",
    "stream_id": "cDHTRL96JEk",
    "filename": "console.js",
    "url": "https://cloudup.com/iMQTrKyW7y5"
  },
  {
    "id": "iWuEYANxI0e",
    "title": "Console",
    "stream_id": "coWI9e7C540",
    "filename": "console.js",
    "url": "https://cloudup.com/iWuEYANxI0e"
  },
  {
    "id": "ibSrrvO5DKh",
    "title": "Console",
    "stream_id": "coHZI068GFg",
    "filename": "console.js",
    "url": "https://cloudup.com/ibSrrvO5DKh"
  },
...

Thumbnails

Whenever possible Cloudup will generate thumbnail images for a given item, currently in 8 distinct sizes. The item.thumbs array documents take the following form:

{
  "url": "http://i.cloudup.com/nxGUb4G89b-3000x3000.jpeg",
  "width": 3000,
  "height": 1988,
  "format": "jpeg",
  "size": {
    "string": "3000x3000",
    "width": 3000,
    "height": 3000
  }
}

When developing your application it's important to note that zero or more of these thumbnails may be available, and are not ordered within the array. The sizes available are:

  • 50x50
  • 150x150
  • 300x300
  • 600x600
  • 900x900
  • 1200x1200
  • 2000x2000
  • 3000x3000

Users

Cloudup's private-by-default nature means that currently API access is limited to the authenticated user, allowing you to request the user's name, username, and avatar images for use in your applications.

Schema

The User schema is as follows, describing the information available to you as a developer.

NameDescriptionType
idunique user identifierstring
nameuser namestring
usernameuser usernamestring
avataruser avatar imagesobject

Get user information

To fetch information about the authenticated user issue a GET request to /user. Avatar images when present take the same form as item thumbnails.

GET /user
{
  "id": "uCBvmQHiG49",
  "name": "Luna Cat",
  "username": "luna",
  "avatar": [...]
}

Examples

The following examples will help you get started using the Cloudup API.

CORS support

This example displays how interacting with our API over CORS is just an oauth token away:

var xhr = new XMLHttpRequest;
xhr.open('GET', 'https://api.cloudup.com/1/streams?access_token=8JgVPXzgvcltgGopqqjINf9lq', false);
xhr.send(null);
console.log(xhr.responseText);

This more complex example shows (sync) item creation and file upload to s3.

<input type="file" onchange="upload(event)">

<script>
  function upload(e) {
    var file = e.target.files[0];
    
    // create item
    var xhr = new XMLHttpRequest;
    xhr.open('POST', 'https://api.cloudup.com/1/items?access_token=8JgVPXzgvcltgGopqqjINf9lq', false);
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.send(JSON.stringify({ filename: file.name }));
    var res = JSON.parse(xhr.responseText);
    
    // boilerplate for s3
    var form = new FormData;
    form.append('key', res.s3_key);
    form.append('AWSAccessKeyId', res.s3_access_key);
    form.append('acl', 'public-read');
    form.append('policy', res.s3_policy);
    form.append('signature', res.s3_signature);
    
    // item-specific
    form.append('Content-Type', file.type);
    form.append('Content-Length', file.size);
    form.append('file', file);
    
    // upload file
    var xhr = new XMLHttpRequest;
    xhr.open('POST', res.s3_url, false);
    xhr.send(form);
    
    // signal completion
    var xhr = new XMLHttpRequest;
    xhr.open('PATCH', 'https://api.cloudup.com/1/items/' + res.id + '?access_token=8JgVPXzgvcltgGopqqjINf9lq', false);
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.send(JSON.stringify({ complete: true }));
  }
</script>