NAV
shell

Introduction

Welcome to the CloudApp developer docs. Here you can find everything you need to integrate your application with CloudApp. You might want to check out other great third-party applications who make use of the API.

You can use the CloudApp API to list your items, upload a file, set expiration and more. The CloudApp API is under development, and some calls are still missing (for example account management). Some of these missing calls are available with our old API. Keep in mind usage of the CloudApp API is bound to our Terms of Service.

Authentication

HTTP Digest is used to authenticate all requests. If reqest is not successfully authenticated response 403 is returned

JSON

You’re probably interested in JSON responses and not HTML. Add the header Accept: application/json on requests to receive JSON and Content-Type: application/json when you’re sending JSON.

Items

Get Items

curl --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     "https://my.cl.ly/v3/items"

The above command returns JSON structured like this:

{
  "data": [
    {
      "slug": "0J0P2A3I1s2p",
      "name": "Image 2015-03-27 at 4.36.39 pm (1).png",
      "created_at": "2015-10-05T23:53:46Z",
      "updated_at": "2015-10-27T12:42:23Z",
      "item_type": "image",
      "view_counter": 0,
      "content_url": "http://cl.ly/image/0J0P2A3I1s2p/Image%202015-03-27%20at%204.36.39%20pm%20(1).png",
      "redirect_url": null,
      "remote_url": "http://f.cl.ly/items/2C230W0V0X3c3L3Y2q3d/Image%202015-03-27%20at%204.36.39%20pm%20(1).png",
      "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
      "thumbnail_url": "https://cl.ly/0J0P2A3I1s2p/thumbnail",
      "share_url": "https://cl.ly/0J0P2A3I1s2p"
    },
    {
      "slug": "3C041n09450S",
      "name": "Image 2015-03-27 at 4.36.39 pm (2).png",
      "created_at": "2015-10-05T23:52:26Z",
      "updated_at": "2015-10-27T12:42:24Z",
      "item_type": "image",
      "view_counter": 0,
      "content_url": "http://cl.ly/image/3C041n09450S/Image%202015-03-27%20at%204.36.39%20pm%20(2).png",
      "redirect_url": null,
      "remote_url": "http://f.cl.ly/items/1R3f2D0f0t053i092q3V/Image%202015-03-27%20at%204.36.39%20pm%20(2).png",
      "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
      "thumbnail_url": "https://cl.ly/0J0P2A3I1s2p/thumbnail",
      "share_url": "https://cl.ly/0J0P2A3I1s2p"
    }
  ],
  "links": {
    "next_url": {
      "method": "GET",
      "href": "https://my.cl.ly/v3/items?before=1444089146&per_page=20"
    },
    "prev_url": {
      "method": "GET",
      "href": "https://my.cl.ly/v3/items?after=1447078556&per_page=20"
    }
  },
  "meta": {
    "count": 39
  }
}

Page through your items

HTTP Request

GET https://my.cl.ly/v3/items

Query Parameters

Parameter Default Description
per_page 20 Number of items per page.

Get a Specific Item

curl --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     "https://my.cl.ly/v3/items/221t0k2V3k13"

The above command returns JSON structured like this:

{
  "slug": "221t0k2V3k13",
  "name": "image.jpg",
  "created_at": "2015-11-12T11:48:35Z",
  "updated_at": "2015-11-12T11:49:06Z",
  "item_type": "image",
  "view_counter": 1,
  "content_url": "http://cl.ly/image/221t0k2V3k13/al%20(6).jpg",
  "redirect_url": null,
  "remote_url": "http://f.cl.ly/items/3Y2i3D1C3N1X283I0H3m/al%20(6).jpg",
  "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
  "thumbnail_url": "https://cl.ly/0J0P2A3I1s2p/thumbnail",
  "share_url": "https://cl.ly/0J0P2A3I1s2p"
}

This endpoint retrieves a specific item.

HTTP Request

GET https://my.cl.ly/v3/items/<ID>

URL Parameters

Parameter Description
ID Item slug (string)

Update Item

curl -X PUT --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "name": "new_name.png", "long_link": false }' \
     "https://my.cl.ly/v3/items/221t0k2V3k13"

The above command returns JSON structured like this:

{
  "slug": "221t0k2V3k13",
  "name": "new_name.jpg",
  "created_at": "2015-11-12T11:48:35Z",
  "updated_at": "2015-11-12T11:49:06Z",
  "long_link": false,
  "item_type": "image",
  "view_counter": 1,
  "content_url": "http://cl.ly/image/221t0k2V3k13/al%20(6).jpg",
  "redirect_url": null,
  "remote_url": "http://f.cl.ly/items/3Y2i3D1C3N1X283I0H3m/al%20(6).jpg",
  "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
  "thumbnail_url": "https://cl.ly/0J0P2A3I1s2p/thumbnail",
  "share_url": "https://cl.ly/0J0P2A3I1s2p"
}

This endpoint updates a specific item, it is allowed to change file name, or long_link (item security level)

HTTP Request

PUT https://my.cl.ly/v3/items/<ID>

URL Parameters

Parameter Description
ID Item slug (string)

Body Parameters

Parameter Default Description
long_link true If set to false it will change link to short one (less secure).
name — Name of file

Delete a Specific Item

curl -X DELETE --digest -u "arthur@dent.com:towel" \
     "https://my.cl.ly/v3/items/221t0k2V3k13"

Response 204

This endpoint removes a specific item

HTTP Request

DELETE https://my.cl.ly/v3/items/<ID>

URL Parameters

Parameter Description
ID Item slug (string)

Add Item (bookmark)

curl -X POST --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "bookmark_url": "http://getcloudapp.com/" }' \
     "https://my.cl.ly/v3/items"

The above command returns JSON structured like this:

{
  "slug": "3W1F1h3I3b0J",
  "name": "http://getcloudapp.com/",
  "created_at": "2015-11-12T11:12:02Z",
  "updated_at": "2015-11-12T11:12:02Z",
  "long_link": true,
  "item_type": "bookmark",
  "view_counter": 0,
  "content_url": null,
  "redirect_url": "http://getcloudapp.com/",
  "remote_url": null,
  "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
  "thumbnail_url": "https://cl.ly/0J0P2A3I1s2p/thumbnail",
  "share_url": "https://cl.ly/0J0P2A3I1s2p"
}

This endpoint creates a bookmark to URL

Body Parameters

Parameter Description
bookmark_url URL

Add item (upload file)

curl -X POST --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Image.png" }' \
     "https://my.cl.ly/v3/items"

For Free user the above command returns JSON structured like this:

{
  "slug": "1h132K0z2n3G",
  "name": "Image.png",
  "url": "http://f.cl.ly",
  "uploads_remaining": 1,
  "max_upload_size": 26214400,
  "s3": {
    "AWSAccessKeyId": "AKIAJP2C6U543KJIE2GA",
    "key": "items/353u2B053p0H0D1O3w1b/${filename}",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0xMS0xMlQxMjo0MTozOFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJjbG91ZGFwcC5jb3BwZXIuaW8ifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIml0ZW1zLzM1M3UyQjA1M3AwSDBEMU8zdzFiLyJdLHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiJodHRwOi8vbXkuY2wuZGV2L3YzL2l0ZW1zLzFoMTMySzB6Mm4zRy9zMyJ9LHsiYWNsIjoicHVibGljLXJlYWQifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDI2MjE0NDAwXV19",
    "signature": "wqSVl9+fvkvtIzGfakNF+drqN0s=",
    "success_action_redirect": "http://api.cl.ly/v3/items/1h132K0z2n3G/s3",
    "acl": "public-read"
  }
}

For Pro user the structured will look like this:

{
  "slug": "1h132K0z2n3G",
  "name": "Image.png",
  "url": "http://f.cl.ly",
  "uploads_remaining": -1,
  "max_upload_size": 524288000,
  "s3": {
    "AWSAccessKeyId": "AKIAJP2C6U543KJIE2GA",
    "key": "items/353u2B053p0H0D1O3w1b/${filename}",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0xMS0xMlQxMjo0MTozOFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJjbG91ZGFwcC5jb3BwZXIuaW8ifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIml0ZW1zLzM1M3UyQjA1M3AwSDBEMU8zdzFiLyJdLHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiJodHRwOi8vbXkuY2wuZGV2L3YzL2l0ZW1zLzFoMTMySzB6Mm4zRy9zMyJ9LHsiYWNsIjoicHVibGljLXJlYWQifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDI2MjE0NDAwXV19",
    "signature": "wqSVl9+fvkvtIzGfakNF+drqN0s=",
    "success_action_redirect": "http://api.cl.ly/v3/items/1h132K0z2n3G/s3",
    "acl": "public-read"
  }
}

To make the CloudApp process as fast as possible, we upload files directly to S3. The process involves: making an initial request to CloudApp, retrieving a few parameters, passing them along with the file itself to S3, following the redirect response back to CloudApp, and finally receiving the details of the newly created item.

Request to Upload

Request to upload a file to CloudApp. If the authenticated account is able to upload a file, the response will be some metadata that must be passed to S3 in order to upload the file. Along with the S3 data, there may be an upload size limitation. We encourage you to take note of the size of the file being uploaded, making sure it’s smaller than than the maximum allowed size. Otherwise the file will be fully uploaded, only to be rejected for being too large.

Body Parameters

Parameter Description
name Name of file
file_size File size in bytes (optional)

Upload File to S3

Use the response from the previous step to construct the file upload request. Each item in s3 becomes a separate parameter you’ll need to post to url. Send the file to be uploaded as the parameter named file.

Request

Show Favorite for Item

curl -X GET --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     "https://my.cl.ly/v3/items/221t0k2V3k13/favorite"

The above command returns JSON structured like this:

{
  "favorite":false
}

Show if item is labeled as favorite

HTTP Request

GET https://my.cl.ly/v3/items/<ID>/favorite

URL Parameters

Parameter Description
ID Item slug (string)

Add a Specific Item to Favorites

curl -X POST --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "favorite": true }' \
     "https://my.cl.ly/v3/items/221t0k2V3k13/favorite"

The above command returns JSON structured like this:

{
  "favorite": true
}

Add item to favorites

HTTP Request

POST https://my.cl.ly/v3/items/<ID>/favorite

URL Parameters

Parameter Description
ID Item slug (string)

Delete Specific Item from Favorites

curl -X DELETE --digest -u "arthur@dent.com:towel" \
     "https://my.cl.ly/v3/items/221t0k2V3k13/favorite"

Response 204

HTTP Request

DELETE https://my.cl.ly/v3/items/<ID>/favorite

URL Parameters

Parameter Description
ID Item slug (string)

Share Item Via Email

curl -X POST --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "recipients": 
            [ "example@test.com", "example2@test.com"] \
         }' \
     "https://my.cl.ly/v3/items/221t0k2V3k13/share"

The above command returns JSON structured like this:

{
  "recipients": [ "example@test.com", "example2@test.com"]
}

Sends an email, including a link to the item, directly to a recipient.

HTTP Request

POST https://my.cl.ly/v3/items/<ID>/share

URL Parameters

Parameter Description
ID Item slug (string)

Body Parameters

Parameter Description
recipients Array with email addresses
message Message added to each email (optional)

Add/Change Expiration for Item

Set date or number of views after which item will be disabled.

curl -X POST --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{ "expires_at": "2016-03-30T18:00:00Z", \
           "expires_after_views": 10 \
         }' \
     "https://my.cl.ly/v3/items/221t0k2V3k13/expiration"

Item will become disabled after 10 views or at ‘2016-03-30T18:00:00Z’, command returns json like this

{
  "expires_at": "2016-03-30T18:00:00Z",
  "expires_after_views": 10
}

HTTP Request

POST https://my.cl.ly/v3/items/<ID>/expiration

URL Parameters

Parameter Description
ID Item slug (string)

Body Parameters

Parameter Description
expires_at Time when item will expire in iso8601 format (optional)
expires_after_views Number of views after which the item will expire (optional)

Show Expiration for Item

Get expirations settings for item.

curl -X GET --digest -u "arthur@dent.com:towel" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     "https://my.cl.ly/v3/items/221t0k2V3k13/expiration"

Response:

{
  "expires_at": "2001-03-30T18:00:00Z",
  "expires_after_views": 7
}

HTTP Request

GET https://my.cl.ly/v3/items/<ID>/expiration

URL Parameters

Parameter Description
ID Item slug (string)

Delete Expiration for Specific Item

Removes all expiration settings for item

curl -X DELETE --digest -u "arthur@dent.com:towel" \
     "https://my.cl.ly/v3/items/221t0k2V3k13/expiration"

Response 204

HTTP Request

DELETE https://my.cl.ly/v3/items/<ID>/expiration

URL Parameters

Parameter Description
ID Item slug (string)

Errors

When request data can’t be processed error code 422 is return together with JSON error message for example:

{
  "errors": {
    "name": "file_size",
    "message": "File size is too large",
    "type": ""
  }
}

The CloudApp API uses the following error codes:

Error Code Meaning
404 Not Found – The specified item could not be found, or user is not an owner of item
403 Forbidden – Digest authentication failed
422 Unprocessable Entity – Wrong request data
500 Internal Server Error – We had a problem with our server, and we are already taking care of it. Try again later.
503 Service Unavailable – Service Unavailable – We’re temporarially offline for maintenance. Please try again later.
shell