Documentation

 Back to top

Introduction 

Add multiple cloud storage services to your app with the Kloudless API. Rather than working through each API individually, code once and your application is instantly connected to multiple cloud services. We take care of the integration and ongoing maintenance, so you can focus on building a great product.

You will need a Kloudless API key to get started. Get one for free by signing up!


Interactive Docs 

After you are familiar with our API you can test it out with your App ID and API Key.

Visit our Interactive Docs to give it a try!


Authentication 

By default, users are authenticated with Kloudless Platform OAuth keys for the cloud storage service they’d like to use. This means that they will see ‘Kloudless Platform’ as the application that they are authorizing to access their account.

However, you can choose to use your own OAuth keys for the cloud storage services you’d like to support. You can configure this in the developer dashboard.

You can either use our web server flow to authenticate users, or the JS library we provide. Both are described in more detail below.

Authenticating via your web server

You can connect your users’ cloud storage accounts to the Kloudless platform by redirecting them to us. We will redirect them back to a callback URL you provide with their account ID and the cloud storage service they chose.

The URL to redirect a user to is of the form:

https://api.kloudless.com/services/?app_id=APP_ID&callback=CALLBACK&services=list,of,services&admin=
  • APP_ID: This is your Kloudless application’s App ID

  • CALLBACK: This is a url-encoded callback URL to send users back to your website after they have connected a cloud storage account. Query parameters will be added to the callback URL:

    • account: The ID of the Account that was connected.
    • service: The name of the service that was connected.
    • error_code: If there is an error, the error code. See the error table below.
    • message: If there is an error, the error message containing details of error.
  • services: Optional. This allows you to only display a subset of services for the user to be able to connect. If only one is provided, we will immediately redirect to it. The service names must be comma-separated, and must be from the list of currently supported services.

  • admin Optional. Set to 1 to request admins to authorize access to their organization’s data. You can then list team members and perform API requests on behalf of them.

Here are some examples:

# Authenticate a user and redirect back to http://localhost:8080/callback
# An example URL redirected to is:
#   http://localhost:8080/callback?account=50&service=box
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback

# Only display Box and Dropbox
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback&services=box,dropbox

# Take the user directly to Dropbox to authenticate
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback&services=dropbox

Kloudless Authenticator JS Library

We’ve provided a JavaScript library that authenticates users to cloud storage services and connects their accounts to your Kloudless app.

The library lets you open a pop-up that allows the user to choose a cloud storage service to connect. The pop-up closes once the account has been successfully connected.

To use it, embed the Kloudless JavaScript library in your page:

<script type="text/javascript"
 src="https://static-cdn.kloudless.com/p/platform/sdk/kloudless.authenticator.v0.1.js"></script>

Check out the Github repository for information on how to use authenticator.js:

https://github.com/kloudless/authenticator.js


Authorization 

A developer can use an Authorization header to authorize requests for the Kloudless API. Kloudless offers two options for an Authorization header: ApiKey or AccountKey.

API Key Authorization

An API key is automatically generated when a developer creates an application. The API key allows a developer to make requests on behalf of all connected accounts. Therefore, the API key should be kept secret at all times. The most common use case will be for server side requests. We use an API key like this:

Authorization: ApiKey {api_key: string}

Here is how you can make a request using cURL:

curl -L -H 'Authorization: ApiKey [KEY]' https://api.kloudless.com/v0/[RESOURCE]

Here are some example requests:

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v0/accounts?active=True

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v0/accounts/1/files/fL3Rlc3QucG5n?overwrite=False

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v0/accounts/1/links

Account Key Authorization

An Account key is automatically created when a user connects an account to the application. A developer can only make a request to a specific account with the associated Account key. The most common use case will be for client side requests. Similar to the API Key, we use an Account key like this:

Authorization: AccountKey {account_key: string}

Here is how you can make a request using cURL:

curl -L -H 'Authorization: AccountKey [KEY]' \
    https://api.kloudless.com/v0/[RESOURCE]

You can also authenticate requests to multiple accounts by comma-separating the necessary Account Keys. For example:

curl -L -H 'Authorization: AccountKey key_123,key_456,key_789' \
    https://api.kloudless.com/v0/accounts/123,456,789/links

For more information on creating and retrieving Account Keys, see here.

Similar to the API Key, Account Keys must be kept secure. They should only be accessible by the account owner and the application developer.

Although client-side requests can be made with Account Keys, we encourage requests to be made through your backend server to Kloudless using your API Key. This will reduce the chances of us having to throttle a particular user if they obtain the Account Key and attempt to DoS your Kloudless App.


Accounts 

Each account represents a cloud storage account that a user has connected to your app.

  • id Unique identifier for this account

  • account Account identifier that can be used to display the user. This is usually the account’s email address, but can be other strings, such as the user’s name if the email cannot be obtained (e.g.: for Evernote).

  • service Service identifier. Indicates which cloud storage service the account is for. Here are the currently supported service identifiers:

    • file_store service group:
      • Dropbox: dropbox
      • Box: box
      • Google Drive: gdrive
      • OneDrive: skydrive
      • Citrix Sharefile: sharefile
      • Barracuda Copy: copy
      • SugarSync: sugarsync
      • Egnyte: egnyte
      • Evernote: evernote
      • SharePoint: sharepoint
      • OneDrive for Business: onedrivebiz
      • CMIS: cmis
      • Alfresco: alfresco
      • WebDAV: webdav (Coming Soon)
    • object_store service group:
      • AWS S3: s3
      • Azure Storage: azure

    Service group names can be used when filtering services to display to a user during authentication or via UI Tools. For example, instead of listing out every single file storarge service, you can just usefile_store instead.

    The special service group all includes all service identifiers.

  • service_name A displayable name for the service. Examples: Google Drive, Amazon S3, Dropbox.

  • active If the account’s tokens are expired, or the account inaccessible, the account will be deactivated and this value will be False.

  • admin True if the account was authenticated using the admin flow. These accounts are intended to grant access to team-wide data.

  • created ISO 8601 timestamp indicating when the account object was created (first connected).

  • modified ISO 8601 timestamp indicating when the account object was modified.

  • token_expiry ISO 8601 timestamp indicating when the token used to access the cloud storage account expires, if at all. eg: For OAuth 2.0, this refers to the expiry time of the access token.

  • refresh_token_expiry ISO 8601 timestamp indicating when the OAuth 2.0 refresh token expires, if using OAuth 2.0 and refresh tokens are present.

  • user_id ID of the user in the service. Corresponds to the User ID returned from the Team endpoint for admin accounts. null if unavailable or not applicable.

  • quota only available when retrieving a specific account, it is a dictionary with:

    • used space in bytes used by the account (can be null for some services).
    • total space in bytes that that account can use in total (can be null for some services).

Please contact us at support@kloudless.com if you would like to retrieve the token and token_secret for accounts via the API. This is useful for direct requests to a service’s API.

List Accounts 

list accountsGET /accounts{?active,page_size,page,admin,ordering,search}

The response contains the following information:

  • total Total number of objects

  • count Number of objects on this page

  • page Page number

  • accounts List of account objects

  • Parameters
  • active
    boolean (optional) 

    Retrieves only active/inactive accounts, if present.

    Choices: True, False

    page_size
    number (optional) Default: 30 

    Number of objects in each page. The page_size must be between 0 and 100.

    page
    number (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. page must be greater than 0.

    admin
    boolean (optional) 

    Retrieves only admin/non-admin accounts, if present.

    Choices: True, False

    ordering
    string (optional) Default: -modified 

    Coming Soon

    search
    string (optional) 

    Coming Soon

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "total": 2,
        "count": 2,
        "page": 1,
        "objects": [
            {
                "id": 90817234,
                "account": "someone@gmail.com",
                "service": "box",
                "service_name": "Box",
                "admin": false,
                "active": true,
                "created": "2015-03-17T20:42:17.954885Z",
                "modified": "2015-03-17T20:42:17.954885Z",
                "token_expiry": "2015-04-17T20:42:17.954885Z",
                "refresh_token_expiry": null,
                "user": "uX1jd9af",
            },
            {
                "id": 6535892,
                "account": "someone-else@gmail.com",
                "service": "egnyte",
                "service_name": "Egnyte",
                "admin": false,
                "active": true,
                "created": "2015-03-17T20:42:18.627533Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "token_expiry": "2015-04-17T20:42:18.627533Z",
                "refresh_token_expiry": null,
                "user": null,
            }
        ]
    }
    

Import an Account 

import an accountPOST /accounts

Account creation is usually handled via Kloudless Authentication. However, this account creation endpoint can be used to import account and token information into Kloudless. This is useful when migrating existing cloud storage API tokens into Kloudless.

Here are the required parameters:

  • account Described above.

  • service Described above.

  • token The token used to authenticate requests to the cloud storage service. eg: For services accessed via OAuth, this is the access token.

In addition, the following optional parameters may be provided:

  • token_secret The OAuth token secret.

  • refresh_token The OAuth 2.0 refresh token.

  • token_expiry Described above.

  • refresh_token_expiry Described above.

For ShareFile, the following additional parameters are required:

  • domain The user’s ShareFile domain. This can be obtained from the response to a request for an access token.

For Egnyte, the following additional parameters are required:

  • domain The user’s Egnyte domain. This can be obtained from the URL users use to access their Egnyte account: https://domain.egnyte.com

For SharePoint and OneDrive for Business, the following additional parameters are required:

Since token information is being imported, the credentials used to authenticate the user and obtain those tokens must be entered into the Kloudless Developer Portal. Otherwise, Kloudless will not be able to use the tokens to perform requests.

Please see our migration guide for more information on how to migrate your app to our service with no downtime. (Coming Soon)

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"account": "someone@gmail.com", "service": "copy", "token": "foo", "token_secret": "bar"}' \
    'https://api.kloudless.com/v0/accounts/'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "account": "someone@gmail.com",
        "service": "copy",
        "token": "foo",
        "token_secret": "bar"
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 92386572,
        "account": "someone@gmail.com",
        "service": "copy",
        "service_name": "Copy",
        "admin": false,
        "active": true,
        "created": "2015-05-15T20:00:00Z",
        "modified": "2015-05-15T20:00:00Z",
        "token_expiry": null,
        "refresh_token_expiry": null,
        "user": null,
    },
    

Retrieve an Account 

retrieve an accountGET /accounts/{account_id}/{?active}
  • Parameters
  • active
    boolean (optional) 

    Retrieves only an active/inactive account, if present.

    Choices: True, False

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 90817234,
        "account": "someone@gmail.com",
        "service": "box",
        "service_name": "Box",
        "admin": false,
        "active": true,
        "created": "2015-03-17T20:42:17.954885Z",
        "modified": "2015-03-17T20:42:17.954885Z",
        "token_expiry": "2015-04-17T20:42:17.954885Z",
        "refresh_token_expiry": null,
        "user": "uX1jd9af",
        "quota": {
            "used": 316317438,
            "total": 2627241831
        }
    }
    

Update an Account 

Update an AccountPATCH /accounts/{account_id}

When importing account/token information, you may wish to update Kloudless’ knowledge of tokens if you refresh them or obtain new tokens for the account. This endpoint will allow you to update the account with new information.

Here are the properties that can be updated:

  • active
  • account
  • service
  • token
  • token_secret
  • refresh_token
  • token_expiry
  • refresh_token_expiry

The new object will be returned on success.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": false}' \
    'https://api.kloudless.com/v0/accounts/15'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "active": false,
    }
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 90817234,
        "account": "someone@gmail.com",
        "service": "box",
        "service_name": "Box",
        "admin": false,
        "active": false,
        "created": "2015-03-17T20:42:17.954885Z",
        "modified": "2015-05-15T06:12:00Z",
        "token_expiry": "2015-04-17T20:42:17.954885Z",
        "refresh_token_expiry": null,
        "user": "uX1jd9af",
    }
    

Delete an Account 

Delete an AccountDELETE /accounts/{account_id}

Example request:

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -XDELETE https://api.kloudless.com/accounts/34
  • Response  204

Account Keys 

Account Keys can be used instead of API Keys to restrict access to a specific account’s data. This is most useful for client-side requests. For more details on using an Account Key, see Account Key Authorization.

  • id Unique identifier for this account key. Although the Account Key itself is unique, we use the ID to identify the resource in API requests for security purposes.

  • key The account key.

  • active Boolean indicating if the key is active or not. An inactive key cannot be used to authenticate requests.

  • expiration ISO 8601 timestamp indicating when the key will expire. May be null. An expired key will behave similar to a deleted key.

  • created ISO 8601 timestamp indicating when the account key was created.

  • modified ISO 8601 timestamp indicating when the link account key was modified.

List Account Keys 

list account keysGET /accounts/{account_id,account_id,...}/keys/{?page_size,page}

The response contains the following information:

  • total Total number of objects

  • count Number of objects on this page

  • page Page number

  • objects List of objects

The keys are sorted in descending order by modified time.

Example request:

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/15/keys'

Note that since the keys endpoint is nested under an account, it is also possible to use the account key for that account itself to make this request:

curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
    'https://api.kloudless.com/v0/accounts/15/keys'

This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be retrieved by separating the account IDs with commas:

curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
    'https://api.kloudless.com/v0/accounts/15,16,17/keys'
  • Parameters
  • page_size
    number (optional) Default: 30 

    Number of objects on each page. The page_size must be between 0 and 100.

    page
    number (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. page must be greater than 0.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "total": 1,
        "count": 1,
        "page": 1,
        "objects": [
            {
                "id": 20,
                "key": "KEI0SUlDSHrBVE1ulVGdmFsRJ",
                "active": true,
                "account": 15,
                "expiration": null,
                "created": "2015-03-12T08:47:59.531726Z",
                "modified": "2015-03-12T08:47:59.531726Z",
             }
         ]
    }
    

Create an Account Key 

Create an Account KeyPOST /accounts/{account_id}/keys/

Coming soon! Let us know at support@kloudless.com if you need this sooner.

  • Response  201

Retrieve an Account Key 

retrieve an account keyGET /accounts/{account_id}/keys/{key_id}/

Example request:

curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
    'https://api.kloudless.com/v0/accounts/15/keys/20'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
     {
                "id": 20,
                "key": "KEI0SUlDSHrBVE1ulVGdmFsRJ",
                "active": true,
                "account": 15,
                "expiration": null,
                "created": "2015-03-12T08:47:59.531726Z",
                "modified": "2015-03-12T08:47:59.531726Z",
     }
    

Update an Account Key 

Update an account keyPATCH /accounts/{account_id}/keys/{key_id}

Coming soon! Let us know at support@kloudless.com if you need this sooner.

  • Response  200

Delete an Account Key 

Delete an account keyDELETE /accounts/{account_id}/keys/{key_id}

Coming soon! Let us know at support@kloudless.com if you need this sooner.

  • Response  204

Files 

File objects represent some data that belong to a particular user.

A file has the following attributes:

  • id Unique identifier for this file. Under the hood: It is an encrypted version of the cloud storage account’s file ID. This value increases in length proportionally with the cloud storage’s file ID. Some services like Dropbox can therefore have very long IDs as folder nesting increases.

  • name File name

  • size File size in bytes. May be null if unknown.

  • created ISO 8601 timestamp indicating when the file was created. May be null if unknown.

  • modified ISO 8601 timestamp indicating when the file was last modified. May be null if unknown.

  • type Will be file.

  • account The id of the account that the file is assocated with.

  • parent An object with metadata on the parent folder. Includes the parent’s id, and name where possible.

  • path A human-readable path to the file in the account. May be null if unknown.

  • mime_type The content type of the file.

  • downloadable A boolean indicating whether the file can be downloaded.

Upload a File 

Upload a FilePOST /accounts/{account_id}/files/{?overwrite}

You can upload files using a multipart POST. You can only upload files to folders that have can_upload_files set to true. See the Folder Resource for more information.

Here is an example:

curl -XPOST -H 'Authorization: ApiKey [KEY]' \
    'https://api.kloudless.com/v0/accounts/123/files' \
    -F metadata='{"parent_id": "fL2hp", "name": "test.png"}' \
    -F file=@FILENAME

You can also upload files from a URL instead, To do this, specify the name, parent_id and url in a JSON request body. For example:

curl -X POST -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    -d '{"name": "test.png", "parent_id": "fL2hp", "url": "http://i.imgur.com/Y9debSL.png"}' \
    'https://api.kloudless.com/v0/accounts/123/files'

We automatically rename uploaded files in the event of name conflicts (unless the overwrite parameter is set to True), so the resulting file name and metadata will be returned upon success. We also enforce restrictions on file names based on the underlying service.

NOTE: Uploads through this endpoint are limited to 100MB, if you would like to upload files larger than this please use the multipart upload endpoint.

  • Parameters
  • overwrite
    boolean (optional) Default: false 

    Specifies whether to overwrite existing files

    Choices: False, True

  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: multipart/form-data; boundary=----------------------------af064662d035
    Body
    ------------------------------af064662d035
    Content-Disposition: form-data; name="metadata"
    
    {"parent_id": "fL2hp", "name": "test.png"}
    ------------------------------af064662d035
    Content-Disposition: form-datal name="file"; filename="FILENAME"
    Content-Type: image/png
    
    [file contents]
    ------------------------------af064662d035--
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL3Rlc3QucG5n",
        "name": "test.png",
        "size": 353953,
        "type": "file",
        "created": "2015-01-22T08:15:30.424173Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": 123,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "image/png",
        "downloadable": true,
    }
    

Retrieve File metadata 

retrieve file metadataGET /accounts/{account_id}/files/{file_id}

This will retrieve the metadata associated with the file object.

Example request:

curl -L -H 'Authorization: ApiKey [KEY]' \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL3Rlc3QucG5n",
        "name": "test.png",
        "size": 353953,
        "type": "file",
        "created": "2015-01-22T08:15:30.424173Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account" : 123,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "image/png",
        "downloadable": true,
    }
    

Rename/Move a File 

update file metadataPATCH /accounts/{account_id}/files/{file_id}

This allows you to modify file objects, which allows one to rename the file, move it to another directory within the current account, or move it to another account.

  • Moving to another directory can be done by updating the parent_id field.

  • Renaming is done by updating the name field.

  • Moving to another account can be done by updating the account field. When moving a file to another account, you must specify the id of the destination folder in parent_id. This will remove the file from the source account, since it is following move semantics.

More than one action can be performed at once. For example, you can transfer the file to another account and give it a different name as is shown in the following example command:

curl -X PATCH -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    -d '{"name": "new-cool-name.png", "parent_id": "fL2hp", "account": 124}' \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "name": "new-cool-name.png",
        "parent_id": "fL2hp",
        "account": 124,
    }
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL2hpL3Rlc3QucG5n",
        "name": "new-cool-name (2).png",
        "size": 353953,
        "type": "file",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": 124,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "image/png",
        "downloadable": true,
    }
    

Update File content 

update binary file contentPUT /accounts/{account_id}/files/{file_id}

This will create a new version/overwrite the file and return the updated metadata for the file object on success.

NOTE: Uploads through this endpoint are limited to 100MB, if you would like to update a file with new contents larger than this use the multipart upload endpoint.

Here is an example command of updating the file contents:

curl -X PUT -H 'Authorization: ApiKey [KEY]' \
    --data-binary @/path/to/local/file \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Body
    [file data binary]
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL2hpL3Rlc3QucG5n",
        "name": "new-cool-name (2).png",
        "size": 353953,
        "type": "file",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-05-20T08:00:00Z",
        "account": 124,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "image/png",
        "downloadable": true,
    }
    

Download a File 

get binary file contentGET /accounts/{account_id}/files/{file_id}/contents

This is a direct download of the file. We proxy the download directly from the cloud storage service so we never store your users’ files.

Example request:

curl -L -H 'Authorization: ApiKey [KEY]' \
    https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/contents'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
  • Response  200Toggle
  • Headers
    Content-Type: [mimetype]
    Body
    [file data binary]
    

Copy a File 

Copy a FilePOST /accounts/{account_id}/files/{file_id}/copy

To make a copy of the file you can specify the following fields in a JSON dictionary to describe the operation that will be performed:

  • parent_id (required): Specifies the parent folder of the copied file.

  • account (optional): Specifies the ID of the account that the file will be copied to. Defaults to the current account.

  • name (optional): Specified the new name that the copied file should have.

Example request:

curl -L -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' -XPOST \
    -d '{"parent_id":"fL2hp", "name":"copied-file.png"}' \
    'https://api.kloudless.com/v0/accounts/12/files/fL3Rlc3QucG5n/copy'

If you wish to move the file rather than copy it, update it’s metadata instead.

  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "name": "copied-file.png",
        "parent_id": "fL2hp",
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL2hpL3Rlc3QucG5n",
        "name": "copied-file.png",
        "size": 353953,
        "type": "file",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": 124,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "image/png",
        "downloadable": true,
    }
    

Delete a File 

Delete a FileDELETE /accounts/{account_id}/files/{file_id}{?permanent}

Files may be permanently deleted, bypassing any Trash folder if present, by setting permanent to True. Some services may still provide a mechanism for users to restore the file.

Example request:

curl -L -H 'Authorization: ApiKey [KEY]' -XDELETE \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
  • Parameters
  • permanent
    boolean (optional) Default: False 

    If False, files will be sent to the service’s Trash folder or equivalent if available. If no Trash is present, the file will be permanently deleted. If True, behaves similarly to no Trash being present and deletes the file.

    Choices: True, False

  • Response  204

List recent Files 

list recent filesGET /accounts/{account_id}/recent{?page_size,page}

This retrieves a list of files in a user’s account, sorted in descending order by modified time.

This feature is available for a subset of services. The services supported are the same as those listed under the events endpoint.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/recent'

This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be retrieved by separating the account IDs with commas:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123,456,789/recent'
  • Parameters
  • page_size
    number (optional) Default: 30 

    Number of objects on each page. The page_size must be between 0 and 100.

    page
    number (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. page must be greater than 0.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "total": 3,
        "count": 3,
        "page": 1,
        "files": [
            {
                "id": "fL2hpL3Rlc3QucG5n",
                "name": "test-1.png",
                "size": 353953,
                "type": "file",
                "created": "2015-03-17T20:42:18.627533Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "account": 123,
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "mime_type": "image/png",
                "downloadable": true,
            },
            {
                "id": "fL2hpL3Rlc3QucG5o",
                "name": "test-2.png",
                "size": 353953,
                "type": "file",
                "created": "2015-03-16T20:42:18.627533Z",
                "modified": "2015-03-16T20:42:18.627533Z",
                "account": 123,
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "mime_type": "image/png",
                "downloadable": true,
            },
            {
                "id": "fL2hpL3Rlc3QucG5x",
                "name": "test-3.png",
                "size": 353953,
                "type": "file",
                "created": "2015-03-15T20:42:18.627533Z",
                "modified": "2015-03-15T20:42:18.627533Z",
                "account": 456,
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "mime_type": "image/png",
                "downloadable": true,
            }
        ]
    }
    
Search for filesGET /accounts/{account_id,account_id,...}/search{?q,page_size,page}

This is a limited release of Search. Services currently supported are:

  • dropbox: file name
  • box: file name and contents
  • gdrive: file name and contents
  • skydrive: file name
  • evernote: file name
  • sharepoint: file name and contents
  • onedrivebiz: file name and contents
  • egnyte: file name and contents
  • sharefile: file name and contents
  • cmis: file name and contents
  • alfresco: file name and contents

with more in the works!

The response contains the following information:

  • count Number of file/folder objects in search results.

  • objects List of file/folder objects in search results, in decreasing order of relevancy.

  • errors Contains account IDs mapped to error responses for any accounts that failed the API request. Only present when performing multi-account searches (see below).

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/search?q=hello+world'

This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be searched by separating the account IDs with commas:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123,456,789/search?q=hello+world'

Search result ordering is determined by the underlying cloud storage service’s search API where possible, or by our search cluster if needed. The search results are evenly interleaved when multiple accounts are searched simultaneously. For example, in the cURL request above, the results would be in the order: Acct. ‘123’ Result #1, 456 #1, 789 #1, 123 #2, 456 #2, 789 #2, etc.

  • Parameters
  • q
    string (required) 

    The terms to search for.

    page_size
    number (optional) Default: 30 

    Coming Soon. Number of objects on each page. The page_size must be between 0 and 100.

    page
    number (optional) Default: 1 

    Coming Soon. Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. page must be greater than 0.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 2,
        "objects": [
            {
                "id": "fxZn2Gnd9v",
                "name": "hello.png",
                "size": null,
                "type": "file",
                "created": "2015-03-17T20:00:00Z",
                "modified": "2015-03-17T20:00:00",
                "account": 123,
                "parent": {
                    "id": "root",
                    "name": "Google Drive"
                },
                "mime_type": "image/png",
                "downloadable": true,
            },
            {
                "id": "fL3Rlc3QucG5n",
                "name": "Around the World in Eight Days.pdf",
                "size": 353953,
                "type": "file",
                "created": "2015-01-22T08:15:30.424173Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "account": 123,
                "parent": {
                    "id": "fN2BVsAty3v2b",
                    "name": "Classics"
                },
                "mime_type": "application/pdf",
                "downloadable": true,
            }
        ]
    }
    

Multipart Upload 

NOTE: This endpoint is only for files larger than 5MB, for smaller files, you must use the standard file upload endpoint.

In order to handle large files in a way that is reliable and resumeable we support uploading files as multiple different parts which are then recombined into a resulting larger file. These parts are tracked by a multipart session object which is managed through this API endpoint.

A multipart session has the following fields:

  • id: the identifier that you use to reference the session and upload parts.

  • name: the name of the file that will be created from all the chunks.

  • parent_id: the identifier of the folder object that the file will be created inside.

The entire upload process is made up of three parts:

  1. Initialize the session
  2. Upload parts
  3. Finalize session

WARNING: If you do not complete or abort a multipart upload it can take up space in your cloud storage account, which for services like Amazon S3 could result in extra storage costs.

Currently multipart uploads are only supported for the following services:

  • s3
  • azure

Other services will have to rely on the standard upload endpoint for files.

Initialize Multipart Session 

Initialize Multipart SessionPOST /accounts/{account_id}/multipart{?overwrite}

In order to begin a multipart session you need to send the desired name of the file that you are uploading and the ID of the folder to upload it to. The response will contain the following information:

  • id: The ID of the new multipart resource you will be interacting with.

  • account: The ID of the account that the multipart resource is assocated with.

  • part_size: Each part but the last must be this size in bytes in order for the upload to succeed.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"parent_id":"root", "name": "test-big-file.iso"}'
    'https://api.kloudless.com/v0/accounts/123/multipart'
  • Parameters
  • overwrite
    boolean (optional) Default: False 

    If True, an existing file with the same name will be overwritten by the uploaded file.

    Choices: True, False

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
        "parent_id": "root",
        "name": "test-big-file.iso"
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 543,
        "account": 123,
        "part_size": 5242880,
    }
    

Retrieve Multipart Session Information 

Retrieve Multipart Session InformationGET /accounts/{account_id}/multipart/{multpart_id}

This endpoint is used to query information about an existing multipart session. The following information is returned:

  • id: The ID of the new multipart resource you will be interacting with.

  • account: The ID of the account that the multipart resource is assocated with.

  • part_size: Each part but the last must be this size in bytes in order for the upload to succeed.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 543,
        "account": 123,
        "part_size": 5242880,
    }
    

Upload Part 

Upload PartPUT /accounts/{account_id}/multipart/{multipart_id}{?part_number}

Parts of a file can be uploaded in any order as long as the part_number corresponds to the order in which the part appears in the original file.

IMPORTANT: All of the parts but the last must be equal to the part size that gets returned when the multipart session gets created. If the file that you are uploading is smaller than that, you should use the normal upload endpoint for files.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/octet-stream' \
    -XPUT --data-binary @test-big-file.iso.part1 \
    'https://api.kloudless.com/v0/accounts/123/multipart/543?part_number=1'
  • Parameters
  • part_number
    integer (required) Example: 1

    The index of the part.

    Choices: [1..10000]

  • RequestToggle
  • Headers
    Content-Type: application/octet-stream
    Body
    <binary contents of file part>
    
  • Response  200

Finalize Multipart Session 

Finalize Multipart SessionPOST /accounts/{account_id}/multipart/{multipart_id}/complete

Once all of the parts are uploaded, the session must be finalized to create the new file. This will combine all of the parts and return the metadata for the new file.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -XPOST 'https://api.kloudless.com/v0/accounts/123/multipart/543/complete'
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL3Rlc3QtYmlnLWZpbGUuaXNvCg==",
        "name": "test-big-file.iso",
        "size": 157286400,
        "type": "file",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": 123,
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "mime_type": "application/octet-stream",
        "downloadable": true,
    }
    

Abort Multipart Session 

Abort Multipart SessionDELETE /accounts/{account_id}/multipart/{multipart_id}

This will abort the upload session and remove all uploaded parts from the upstream cloud storage service. This must be done if you do not want to resume a multipart upload session and do not want to incur additional storage charges from the upstream service.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -XDELETE 'https://api.kloudless.com/v0/accounts/123/multipart/543'
  • Response  204

Folders 

Folders are represented as objects that contain a list of file objects. They have metadata and contents similar to that of Files, with a couple of differences:

  • The type will be “folder”.

  • The mime_type and downloadable fields will be absent.

  • Folder “contents” are simply a list of the child files and folders.

The id field has a special value root, which specifies the root directory of the account, and trash which specifies the Trash if available. These folders cannot be moved, renamed, or deleted and attempting to do so will result in an error.

Folders have two extra fields indicating contents that can be added to them:

  • can_create_folders: Indicates if folders can be created within this folder.

  • can_upload_files: Indicates if files can be uploaded to this folder.

These attributes are usually true, but will be false for certain folders such as the root ShareFile folder.

Create a Folder 

Create a FolderPOST /accounts/{account_id}/folders/{?conflict_if_exists}

When creating folders, we do not rename them if a folder of the same name exists; we simply return the ID of the existing folder with that name. This behavior will be configurable soon.

Some services contain special folders in which you cannot create new folders, and we will return an error if you attempt to do so. These folders will have can_create_folders set to false in their metadata.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"parent_id":"root", "name": "New folder inside root dir"}' \
    'https://api.kloudless.com/v0/accounts/123/folders'
  • Parameters
  • conflict_if_exists
    boolean (optional) Default: False 

    If False, this will search for and return an existing folder with the same name if present, rather than attempting to create the folder. If True, this may result in an error with status code 409 if the location already contains a folder with the same name.

    Choices: True, False

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
        "parent_id": "root",
        "name": "New folder inside root directory"
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fTmV3IEZvbGRlcg==",
        "name": "New Folder inside root directory",
        "size": 5135,
        "type": "folder",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": "123",
        "can_create_folders": true,
        "can_upload_files": true,
        "parent": {
            "id": "root",
            "name": "Google Drive",
        },
    }
    

Retrieve Folder Metadata 

Retrieve Folder MetadataGET /accounts/{account_id}/folders/{folder_id}

Example request:

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fTmV3IEZvbGRlcg==",
        "name": "New Folder",
        "size": 5135,
        "type": "folder",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": "123",
        "can_create_folders": true,
        "can_upload_files": true,
        "parent": {
            "id": "root",
            "name": "Google Drive",
        },
    }
    

Retrieve Folder Contents 

Retrieve Folder ContentsGET /accounts/{account_id}/folders/{folder_id}/contents{?page_number,page_size}

The folder_id root can be used to list the contents of the root folder.

The response contains the following information:

  • count Number of child files/folders in this folder.
  • objects List of file/folder objects.
  • page Index of returned page
  • has_next Whether there is a next page.

NOTE: When retrieving children from folders, it is recommended that you use as large a page size as you can in order to avoid having to make too many requests.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/contents'

The folder_id trash can be used to list the Trash or Recycle Bin for the following services:

  • box
  • gdrive
  • sharepoint
  • onedrivebiz
  • Parameters
  • page
    integer (optional) Default: 1 

    The number of the page you wish to fetch, must be greater than 0.

    page_size
    integer (optional) Default: 1000 

    The number of elements per page that should be returned, must be greater than or equal to 100 and less than or equal to 1000.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 2,
        "page": 1,
        "has_next": false,
        "objects": [
            {
                "id": "fyGb2xkZXIgTmFtZQ==",
                "name": "Child Folder",
                "size": null,
                "type": "folder",
                "created": "2015-03-17T20:42:18.627533Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "account": 123,
                "can_create_folders": true,
                "can_upload_files": true,
                "parent": {
                    "id": "root",
                    "name": "Google Drive",
                },
            },
            {
                "id": "fL3Rlc3QucG5n",
                "name": "test.png",
                "size": 353953,
                "type": "file",
                "created": "2015-01-22T08:15:30.424173Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "account": 123,
                "parent": {
                    "id": "root",
                    "name": "Google Drive",
                },
                "mime_type": "image/png",
                "downloadable": true,
            }
        ]
    }
    

Rename/Move a Folder 

Update Folder metadataPATCH /accounts/{account_id}/folders/{folder_id}

Renaming or moving folders can be done in the same way as files: by changing the name and/or parent_id of the folder object respectively. The new metadata is returned. We currently do not support moving entire folders between cloud storage accounts.

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' -XPATCH \
    -d '{"parent_id": "faGVycGFkZXJwZGlyCg==", "name": "New Folder Name"}' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "parent_id": "faGVycGFkZXJwZGlyCg==",
        "name": "New Folder Name"
    }
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL2hpL05ldyBGb2xkZXIgTmFtZQ==",
        "name": "New Folder Name",
        "size": 5135,
        "type": "folder",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": "123",
        "can_create_folders": true,
        "can_upload_files": true,
        "parent": {
            "id": "faGVycGFkZXJwZGlyCg==",
            "name": "New Folder",
        },
    }
    

Copy a Folder 

Copy a FolderPOST /accounts{account_id}/folders/{folder_id}/copy

NOTE: We do not currently support transferring folders between accounts.

This is a beta release, with limited support. Some services require custom OAuth credentials, configurable through the developer portal, to prevent rate-limiting:

  • gdrive
  • sharepoint
  • onedrivebiz
  • skydrive
  • sugarsync
  • s3

NOTE: Response times for the above services scale with the size of the folder being copied, and currently do not succeed if it takes longer than 15 minutes to process.

The following services are also supported, but do not require custom OAuth credentials:

  • dropbox
  • box
  • sharefile
  • evernote

To make a copy of the folder you can specify the following fields in a JSON dictionary to describe the operation that will be performed:

  • parent_id (required): Specifies the parent folder of the copied file.

  • name (optional): Specified the new name that the copied file should have.

Example request:

curl -L -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' -XPOST \
    -d '{"parent_id":"fL2hp", "name":"Copied Folder"}' \
    'https://api.kloudless.com/v0/accounts/12/folders/fL3Rlc3QucG5n/copy'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "name": "Copied Folder",
        "parent_id": "fL2hp",
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "fL2hpL3Rlc3QucG5n",
        "name": "Copied Folder",
        "size": 353953,
        "type": "folder",
        "created": "2015-03-17T20:42:18.627533Z",
        "modified": "2015-03-17T20:42:18.627533Z",
        "account": 12,
        "can_create_folders": true,
        "can_upload_files": true,
        "parent": {
            "id": "fL2hp",
            "name": "New Folder",
        },
    }
    

Delete a Folder 

Delete a FolderDELETE /accounts/{account_id}/folders/{folder_id}{?recursive,permanent}

Deleting a folder can be done recursively or only if the folder is empty by setting the recursive parameter to True or False respectively.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' -XDELETE \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
  • Parameters
  • recursive
    boolean (optional) Default: False 

    If True, folders will be deleted even if they are not empty.

    Choices: True, False

    permanent
    boolean (optional) Default: False 

    If False, folders will be sent to the service’s Trash folder or equivalent if available. If no Trash is present, the folder will be deleted. If True, behaves similarly to no Trash being present and deletes the folder.

    Choices: True, False

  • Response  204

Permissions 

Permissions allow you to grant or revoke access to files or folders in an account. Requests are performed to the appropriate file or folder’s permissions endpoint. Permissions objects consist of the following fields:

  • id The underlying service’s permission identifier (if it exists).

  • email The user’s email, which is associated with this permission.

  • role The user’s role, which is one of:

    • previewer Grants ability to view previews of this resource.

    • reader Grants ability to view this resource.

    • writer Grants ability to view and edit this resource.

    • owner Grants all capabilities to the user, and assigns the user as an owner of the resource.

This feature is not available for all services. Services currently supported are:

  • box
  • gdrive

NOTE: Each service has it’s own unique way of implementing permissions. We attempt to provide the closest match to the storage service’s permissions. Some examples:

  • box provides information on permissions for shared folders and allows you to add, update, and remove permissions.

  • dropbox only provides information on permissions for shared folders.

  • gdrive provides information on permissions for files or shared folders and allows you to add, update, and remove permissions.

List Permissions 

List permissionsGET /accounts/{account_id}/{files,folders}/{file_id,folder_id}/permissions

Retrieves all permission information associated with a file or folder ID.

The response contains the following information:

  • permissions A list of permission information belonging to this resource. Each object contains information as described in Permissions above.

Example request:

curl -L -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/permissions'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "permissions": [
            {
                "id": 94421047,
                "email": "user@test.com",
                "role": "writer"
             }
         ]
    }
    

Set Permissions 

Set permissionsPUT /accounts/{account_id}/{files,folders}/{file_id,folder_id}/permissions

To set permissions on a resource, create a JSON object with each key as an email and value as the role to assign. All permissions for the resource must be specified. Any existing permissions on the resource will be overwritten.

If you would prefer to only alter a subset of permissions, check out the PATCH endpoint instead.

The JSON object in the request consists of:

  • email The email of the user you’re setting permissions for

  • role The user’s role, as described above in Permissions.

    • If you specify an empty string "" it will remove any permissions belonging to this user

If you PUT an empty JSON object {}, it will remove all permissions for this resource.

For example:

    {
        "reader@test.com": "reader",
        "writer@test.com": "writer",
        "previewer@test.com": ""
    }

The response contains permission information in the same format as returned by the list endpoint.

Example request:

curl -X PUT -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"writer@test.com": "writer", "reader@test.com": ""}'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "writer@test.com": "writer",
        "reader@test.com": ""
    }
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "permissions": [
            {
                "id": 54288134,
                "email": "writer@test.com",
                "role": "writer"
            }
         ]
    }
    

Update Permissions 

Update permissionsPATCH /accounts/{account_id}/{files,folders}/{file_id,folder_id}/permissions

To update permissions on a resource, create a JSON object with the user’s email set to the appropriate role. See the PUT endpoint for more information on the request and response format.

Example request:

curl -XPATCH -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    -d '{"writer@test.com": "writer", "reader@test.com": "", "previewer@test.com": "previewer"}'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "writer@test.com": "writer",
        "reader@test.com": "",
        "previewer@test.com": "previewer"
    }
    
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "permissions": [
            {
                "id": 54288134,
                "email": "writer@test.com",
                "role": "writer"
            },
            {
                "id": 211581041,
                "email": "previewer@test.com",
                "role": "previewer"
            }
         ]
    }
    

Links allow you to obtain a file’s public URL that can be used to view or download the file.

  • id Unique identifier for this link. Less than 65 characters long.

  • file_id File ID of the file that the link points to.

  • file_name Name of the file that the link pointed to at the time of creation.

  • url URL that can be used to view or download the file. direct links (see below) allow a querystring inline=true to be added to the URL to ensure the Content Disposition of the downloaded file is “inline” rather than “attachment”. This is useful when embedding links in web pages.

  • account Account ID for the account which contains the file that the link points to.

  • active Boolean indicating if the link is active or not. An inactive link will display an error page indicating that it is inactive and will not allow the user to obtain the file.

  • password Boolean indicating if the link is protected with a password or not.

  • expiration ISO 8601 timestamp indicating when the link will expire. May be null. An expired link will behave similar to a deleted link.

  • created ISO 8601 timestamp indicating when the link object was created.

  • modified ISO 8601 timestamp indicating when the link object was modified.

  • direct If true, resolves directly to the contents of the file and downloads it. If false, resolves to the link generated by the underlying cloud storage service and redirects to it to view the file. Note that a link that isn’t direct will create a shareable link in the underlying service.

Create a LinkPOST /accounts/{account_id}/links/

To create a new link, just post a JSON hash with these parameters:

  • file_id The ID of the file to link to.

In addition, the following optional parameters can be included:

  • password Password for the link

  • expiration ISO 8601 timestamp specifying when the link expires.

  • direct Boolean specifying whether this link is a direct link or not.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "fMEI0H4PP5", "expiration": "2015-01-01T00:00:00"}' \
    'https://api.kloudless.com/v0/accounts/15/links'

To make a direct link:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "fMEI0H4PP5", "direct": true}' \
    'https://api.kloudless.com/v0/accounts/15/links'
  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
        "file_id": "fMEI0H4PP5",
        "expiration": "2015-01-01T00:00:00",
    }
    
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "aZ9APHB0OrTTP74ia9xc",
        "active": true,
        "file_id": "fMEI0H4PP5",
        "account": 15,
        "url": "https://developers.kloudless.com/l/aZ9APHB0OrTTP74ia9xc",
        "expiration": "2015-01-01T00:00:00Z",
        "password": false,
        "created": "2015-03-12T08:47:59.531726Z",
        "modified": "2015-03-12T08:47:59.531726Z",
        "direct": false,
     }
    

WebHooks 

WebHooks are a way to become notified when new events become available for one of the accounts belonging to your application. Having an active webhook is required for generating events on your connected accounts. Webhooks can be created in the Application Details section of the developer portal. When the webhook is created, it will be tested by our servers to ensure that it works before saving it. In order for the test to “pass” your application should respond with a 200 OK status and have just your application ID in the response body. The test webhook request is a POST with an empty request body.

Here is an example standard webhooks requests:

POST / HTTP/1.1
Host: yourapp.example.com
Accept-Encoding: identity
Content-Length: 14
X-Kloudless-Signature: DojsMH34VH3sD+lB8sNBRwkbc7FXyCIRvEbijoCOz9I=
Content-Type: application/x-www-form-urlencoded
User-Agent: kloudless-webhook/1.0

account=593652

The most important part of the POST request above is the body, which is a normal HTTP form. The body of the form contains a single field, account, the value of which is the ID of the account that triggered the event. There will only be one account in each webhook request.

We provide a signature of the request that you can use to ensure that the request came from us and is untampered with. Here is how the signature is defined:

Base64Encode(HMAC-SHA256(<application secret>, <request contents>))

NOTE: Even though there is a signature, you should accept webhook requests over HTTPS if possible. This ensures that data is not leaked to or tampered with by third parties.

This feature is available for a subset of services. The services supported are the same as those listed under the events endpoint.


Events 

Actions such as creating, modifiying, or deleting files and folders generate events that we track. They are represented as a stream of event objects. We currently present the following types of events:

  • add: a resource has been created
  • delete: a resource has been deleted
  • update: a resource has been modified
  • rename: a resource has been renamed
  • move: a resource has been moved

NOTE: We will return the most specific event where possible; otherwise, we will return add or delete as specified by the underlying service.

We will be deprecating the notation of events with the following format in v1:

  • +: either a creation or a modification
  • -: a deletion

Event objects have the following fields:

  • id: The id of the file that the event refers to

  • event_id: The id of the event that is created

  • account: The id of the account the file belongs to

  • action: Either + or - indicating what was done to the file. This will be deprecated in v1. Please use type.

  • modified: The time the event occurred. This is not always precise due to the underlying service

  • type: Any of the types described in Event types

  • metadata: The new metadata of the file or null if the action is delete

  • previous_metadata: The metadata of the previous resource for a rename, move, or copy, which will at least be the previous ID resource. Otherwise, this field will be {}.

  • user_id: For admin credentials, this field specifies the ID of the user responsible for the event.

NOTE: The id field will be deprecated in favor of event_id in v1, but will retain the same name to designate the id of the event.

This feature is not available for all services. Services currently supported are:

  • dropbox
  • box
  • gdrive
  • skydrive
  • evernote
  • sharepoint
  • onedrivebiz
  • sharefile
  • egnyte
  • cmis
  • alfresco

Event data may not be updated right away. The following services notify Kloudless of changes to users’ accounts, with event data updated in at most 1.5 minutes:

  • dropbox
  • box
  • gdrive
  • evernote

Other services require that we poll to traverse the underlying file tree in order to find changes. This means that for the following services, event data will be updated on average every 15 minutes:

  • skydrive
  • sharepoint
  • onedrivebiz
  • sharefile
  • egnyte

CMIS general and specific services also poll for changes. To enable more efficient changes, please configure the repository for change logs. Kloudless will use the content changes to update events.

  • cmis
  • alfresco

NOTE: Events are stored by us for one week, regardless of whether or not they have been retrieved by an application. These are primarily meant as a means to keep stored data about user files up to date and should not be used as the means to generate a snapshot of the whole file system. It is also important to note that events are only generated by services that have an active webhook associated with their application. This is to dissuade applications from relying on inefficient polling for changes to accounts.

List File/Folder Events 

list file/folder eventsGET /accounts/{account_id}/events{?cursor}

Events are retrieved using this endpoint. They are returned as a list of event objects in the order that our system was made aware of them. There is a small chance that there will be duplicate events in the stream, but the net result of applying all of these events will reflect the current state of the underlying storage service.

The response contains the following fields:

  • objects: List of the file/folder events that have taken place

  • cursor: A number identifying a location in the stream immediately after the events described in objects.

  • count: Number of events returned

The returned cursor should be used in subsequent requests so that only events that have not been seen previously are returned.

Example Request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/events?cursor=121'
  • Parameters
  • cursor
    string (optional) 

    The last cursor in the event stream that your application has seen. The cursor can also be set to after-auth, which will retrieve events that have occurred after the account was connected. This is useful if prior events are unnecessary.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "objects": [
        {
          "metadata": {
            "size": 5422,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==",
            "type": "file",
            "account": 613076,
            "name": "logo_white_146x58.png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "created": null,
            "modified": "2015-10-02T21:38:03Z",
            "can_upload_files": null,
            "can_create_folders": null,
            "path": "/Shared Documents/logo_white_146x58.png"
          },
          "action": "+",
          "account": 613076,
          "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==",
          "event_id": 320,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "created": null,
            "modified": "2015-10-02T20:52:41Z",
            "can_upload_files": null,
            "can_create_folders": null,
            "path": "/Shared Documents/test (2).png"
          },
          "action": "+",
          "account": 613076,
          "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
          "event_id": 326,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "created": null,
            "modified": "2015-10-02T20:52:45Z",
            "can_upload_files": null,
            "can_create_folders": null,
            "path": "/Shared Documents/test (2).png"
          },
          "action": "-",
          "account": 613076,
          "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
          "event_id": 330,
          "user_id": null,
          "type": "delete",
          "previous_metadata": {},
        }
      ],
      "cursor": 330
    }
    

Retrieve Latest Cursor 

Retrieve Latest CursorGET /accounts/{account_id}/events/latest

This returns the latest cursor that is available. This makes it easier to start fetching new events immediately, rather than making a potentially large intial request.

This returns a dictionary with a single field:

  • cursor: The most recent cursor for this account

Example Request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/events/latest'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "cursor": 29
    }
    

Team 

The Team endpoints are intended for use with admin accounts connected to your Kloudless application. Admins can authenticate access to their entire organization’s data.

Requests can then be performed on behalf of each user of the organization by setting the header X-Kloudless-As-User to the appropriate user’s ID. These IDs can be retrieved by listing all of the team’s users.

For all requests in this section, the account_id in the URL must correspond to an admin account that has authorized access to team data.

NOTE: These endpoints use an improved pagination format that is not compatible with the pagination used in the folder contents endpoint. This will be adopted for other endpoints as well in future versions of the API.

List Users 

List usersGET /accounts/{account_id}/team/users{?page_size,page}

Services currently supported are:

  • dropbox
  • gdrive
  • box
  • egnyte
  • sharepoint
  • onedrivebiz

with more in the works, including cmis, sharepoint and onedrivebiz.

The response contains the following information:

  • count Number of users on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of users. Each user object has:

    • id The ID of the user. Use this as the value of the X-Kloudless-As-User header to perform API requests as this user.

    • name The name of the user.

    • email An email associated with the user.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/users'
  • Parameters
  • page_size
    number (optional) Default: 1000 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000.

    page
    string (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. Each response will contain the next page’s identifier in the next_page attribute. That identifier must be provided here to retrieve the next page.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 1,
        "next_page": null,
        "page": "1",
        "objects": [
            {
                "id": "u4806226",
                "name": "Test User",
                "email": "user@test.com",
            },
        ],
    }
    

Retrieve a User 

Retrieve a userGET /accounts/{account_id}/team/users/{user_id}

Services currently supported are:

  • box
  • sharepoint
  • onedrivebiz

The response contains the following information:

  • id The ID of the user. Use this as the value of the X-Kloudless-As-User header to perform API requests as this user.

  • name The name of the user.

  • email An email associated with the user.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/users/u4806226'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "u4806226",
        "name": "Test User",
        "email": "user@test.com",
    }
    

List a User's Group Memberships 

List a user's group membershipsGET /accounts/{account_id}/team/users/{user_id}/memberships{?page_size,page}

Services currently supported are:

  • box
  • sharepoint
  • onedrivebiz

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of groups the user is in. Each group object has:

    • id The ID of the group.

    • name The name of the group.

    • role The role of the user in the group. May be one of the following:

      • member: The user is a member of the group.
      • admin: The user is an admin of the group.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/users/u4806226/memberships'
  • Parameters
  • page_size
    number (optional) Default: 1000 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000.

    page
    string (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. Each response will contain the next page’s identifier in the next_page attribute. That identifier must be provided here to retrieve the next page.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 1,
        "next_page": null,
        "page": "1",
        "objects": [
            {
                "id": "g982734",
                "name": "Test Group",
                "role": "admin",
            },
        ],
    }
    

List Groups 

List groupsGET /accounts/{account_id}/team/groups{?page_size,page}

Services currently supported are:

  • box
  • sharepoint
  • onedrivebiz

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of groups. Each group has:

    • id The ID of the group.

    • name The name of the group.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/groups'
  • Parameters
  • page_size
    number (optional) Default: 1000 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000.

    page
    string (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. Each response will contain the next page’s identifier in the next_page attribute. That identifier must be provided here to retrieve the next page.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 1,
        "next_page": null,
        "page": "1",
        "objects": [
            {
                "id": "g982734",
                "name": "Test Group",
            },
        ],
    }
    

Retrieve a Group 

Retrieve a groupGET /accounts/{account_id}/team/groups/{group_id}

Services currently supported are:

  • box
  • sharepoint
  • onedrivebiz

The response contains the following information:

  • id The ID of the group.

  • name The name of the group.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/groups/g982734'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "g982734",
        "name": "Test Group",
    }
    

List a Group's Members 

List a group's membersGET /accounts/{account_id}/team/groups/{group_id}/members{?page_size,page}

Services currently supported are:

  • box
  • sharepoint
  • onedrivebiz

The response contains the following information:

  • count Number of objects on this page.

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of the group’s users. Each object has:

    • id The ID of the user.

    • name The name of the user.

    • email The email address of the user.

    • role The role of the user in the group. See role in group memberships.

Example request:

curl -H 'Authorization: ApiKey XxijaFsSvrgHa8mDvhQ6DF' \
    'https://api.kloudless.com/v0/accounts/123/team/groups/g982734/members'
  • Parameters
  • page_size
    number (optional) Default: 1000 

    Number of objects on each page. The page_size must be greater than or equal to 100 and less than or equal to 1000.

    page
    string (optional) Default: 1 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects. Each response will contain the next page’s identifier in the next_page attribute. That identifier must be provided here to retrieve the next page.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 1,
        "next_page": null,
        "page": "1",
        "objects": [
            {
                "id": "u4806226",
                "name": "Test User",
                "email": "user@test.com",
                "role": "admin",
            },
        ],
    }
    

Errors 

Error Code Table

Error Code Status Code Description
bad_request 400 The request is malformed. Check the message for the reason.
request_failed 400 The request failed. Check the message for the reason.
invalid_parent_folder 400 Invalid parent folder_id parameter.
invalid_parameters 400 The request is malformed: the parameters are incorrect.
invalid_resource_type 400 The resource_type provided is not correct.
unauthorized 401 The Kloudless credentials or token provided are invalid.
service_unauthorized 401 The credentials or token provided for the upstream cloud storage service are invalid.
authentication_required 401 An authorization parameter is missing.
invalid_token 401 Invalid request token provided.
folder_not_empty 403 Cannot delete the folder as it is not empty and the recursive parameter is not set to True.
permission_denied 403 Unable to access resource.
forbidden 403 Forbidden request made to Kloudless.
service_forbidden 403 Forbidden request made to the upstream cloud storage service.
not_found 404 The requested resource was not found.
method_not_allowed 405 The request was made using an unsupported method.
not_acceptable 406 The request was made with unacceptable data.
naming_conflict 409 Resource already exists. Checking the conflicting_resource_id parameter in the response.
too_many_requests 429 Too many requests to the Kloudless API were made. Check the Retry-After header.
too_many_service_requests 429 Too many requests to the underlying service API were made. Check the Retry-After header.
method_not_allowed 500 The request was made by Kloudless with an unsupported method.*
internal_error 500 Kloudless experienced an internal error.*
link_error 500 Kloudless experienced an error retrieving link data.*
unsupported_media_type 500 Kloudless experienced an error making an invalid request.*
not_implemented 501 The request method is not currently implemented for the cloud storage service.
bad_gateway 502 Kloudless received an invalid response from the upstream cloud storage service.
service_not_available 503 The upstream cloud storage service is unavailable.
gateway_timeout 504 The upstream cloud storage service is unavailable.
insufficient_storage 507 There is not enough free space in the cloud storage account to complete the request.

* Contact us at support@kloudless.com for error resolution. It would be helpful to include the id field if present (see below).

Error Message Format

Error messages, along with the status code, contain a JSON object that always has the fields error_code and message, and may contain other useful fields.

  • error_code Short label identifying the error. See above for a list of error codes.

  • message A description of the error.

  • id A unique id for the API request made, if available.

  • status_code HTTP status code of the response.

  • conflicting_resource_id If the error is a naming_conflict (409), the existing resource_id that the API request conflicts with.


Software Development Kits 

We have currently created open source SDKs for the following languages:

Our SDKs make it simple to interact with our API through your language of choice and expose all of the existing functionality of our API. For more details, check out the GitHub repositories.


UI Tools 

Kloudless provides UI Tools built on the API to speed up integration time. These widgets enable the developer to drop in Kloudless API functionality through a common interface for their users to interact with their files.

JS File Explorer

The File Explorer allows your users to browse and select files and folders from their storage services.

Check out the Github repository for more information:

https://github.com/kloudless/file-explorer

Also check out our JSFiddle example of the File Explorer.


Example Apps 

We have a few example apps that may help you out with the implementation:


Getting Help 

If you have any trouble, please let us know by emailing us, opening an issue in the relevant GitHub repository or on Stack Overflow, reaching out to us on Twitter @KloudlessAPI, or chatting with us on IRC on FreeNode in #kloudless.