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.

Name	Description	Type
id	unique stream identifier	string
title	stream title	string
creator_id	stream owner's identifier	string
created_at	stream creation date	date
updated_at	stream update date	date
items	items in the stream	array
url	cloudup stream url	string

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.

Name	Description	Type
id	unique item identifier	string
title	item title	string
stream_id	associated stream id	string
type	item type: code, file, embed, url, article, unknown	string
filename	item filename	string
size	file size in bytes	number
progress	item upload progress	number
url	cloudup item url	string
direct_url	url of the original item upload	string
mime	item mime type	string
width	item image width	number
height	item image height	number
exif	EXIF tags	object
thumbs	item thumbnails	object
thumb_url	initial item thumbnail	string
thumb	thumbnail filename	string
thumb_width	item thumbnail image width	number
thumb_height	item thumbnail image height	number
transcode_state	video transcoding job state: submitted, progressing, complete, canceled, error	string
transcode_url	url of the transcoded video file	string
html	html representation	string
html_thumb	html 'thumbnail' snippet	string
creator_id	item owner's identifier	string
created_at	item creation date	date
progress_at	item progress update date	date
completed_at	item upload completion date	date
complete	item upload success flag	boolean
s3_key	s3 object upload key	string
s3_policy	s3 serialized policy for request usage	string
s3_signature	s3 policy signature for request usage	string
s3_url	s3 url for issuing the POST request	string
s3_access_key	s3 access key for request usage	string
oembed_url	oembed url	string
oembed_html	oembed html	string
oembed_type	oembed type	string
oembed_width	oembed width	number
oembed_height	oembed height	number
oembed_thumbnail_url	oembed thumbnail url	string
oembed_provider_name	oembed provider	string

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.

Name	Description	Type
id	unique user identifier	string
name	user name	string
username	user username	string
avatar	user avatar images	object

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>