Storage API Docs

 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!

Kloudless Enterprise customers can use the Management API to manage their Kloudless Developer Account, its Applications and API Keys.


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 

Please refer to the Authentication docs for more information on connecting user accounts to your Kloudless application.


Authorization 

Please refer to the Authorization section of the Authentication docs for more information on authorizing API requests.


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 Online: sharepoint
      • OneDrive for Business: onedrivebiz
      • CMIS: cmis
      • Alfresco: alfresco
      • Alfresco Cloud: alfresco_cloud
      • Salesforce: salesforce
      • HubSpot Files: hubspot
      • SMB: smb
      • Jive: jive
      • WebDAV: webdav
      • Adobe CQ5: cq5
    • object_store service group:
      • Amazon 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 storage service, you can just use file_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 org-wide data, either by virtue of the admin user having access to all data (such as for SharePoint) or by impersonating individual users.

    Here are supported services:

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

    Not all services require admin authentication to provide access to all data. e.g. s3, sharefile.

  • 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. e.g.: 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 provided when retrieving metadata of 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, token_secret, or account_id (original account’s ID) 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

  • objects List of account objects

  • Parameters
  • active
    boolean (optional) 

    Retrieves only active/inactive accounts, if present.

    Choices: True False

    page_size
    number (optional) Default: 10 

    Number of objects in each page. The page_size must be between 1 and 1000.

    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_id": "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_id": 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. e.g.: 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.

Certain services require a few additional parameters as mentioned below.

  • sharefile
    • domain The user’s ShareFile domain. This can be obtained from the response to a request for an access token.
  • egnyte
    • domain The user’s Egnyte domain. This can be obtained from the URL users use to access their Egnyte account: https://domain.egnyte.com
  • smb
    • domain The host (and port if non-default) of the SMB server. For example, smb.company.com:1399
  • webdav
    • protocol: The WebDAV URL protocol. e.g. http
    • host: The WebDAV host URL. e.g. host.example.com
    • port: The WebDAV port. e.g. 80
    • path: The WebDAV path. e.g. webdav
  • cq5
    • protocol: The Adobe CQ5 URL protocol. e.g. http
    • host: The Adobe CQ5 host URL. e.g. host.example.com
    • port: The Adobe CQ5 port. e.g. 80
    • path: The Adobe CQ5 path, which contains the following joined by a forward slash /:
      • crx-path e.g. crx
      • repository e.g. repository
      • workspace e.g. crx.default
      • The example path would then be crx/repository/crx.default
    • For more information, please visit: https://docs.adobe.com/docs/en/crx/2-3/how_to/webdav_access.html
  • salesforce
    • instance_url Identifies the Salesforce instance to which API calls should be sent. e.g. https://na1.salesforce.com
    • identity_url Identity URL that can be used to both identify the user as well as query for more information about the user. e.g. https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P
  • dynamics
    • resource The URL of the user’s Dynamics CRM portal. e.g. https://mydomain.crm.dynamics.com
  • oracle
    • server_url The Oracle Sales Cloud Host Server URL. e.g. https://123.crm.oraclecloud.com

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 contact us for more information on how to migrate your app to our service with close to no downtime.

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_id": null,
    }

Retrieve an Account 

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

    Retrieves only an active/inactive account, if present.

    Choices: True False

    retrieve_tokens
    boolean (optional) Default: False 

    Retrieves token, token_secret and account_id for an account. Please contact support@kloudless.com to enable access.

    Choices: True False

    retrieve_full
    boolean (optional) Default: True 

    Queries the service for additional information and includes it in the metadata for the account. At the current time, this option populates the quota field. This parameter can be set to False for efficiency reasons if only the other account metadata is required.

    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_id": "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: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": false}' \
    'https://api.kloudless.com/v0/accounts/15'

Note that setting an account to inactive will cease attempts to refresh the account’s refresh_token causing the token to expire after the refresh_token_expiry if present. The user would then have to reconnect their account to reactivate it.

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    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_id": "uX1jd9af",
    }

Delete an Account 

Delete an AccountDELETE /accounts/{account_id}

Example request:

curl -L -H 'Authorization: APIKey [KEY]' \
    -XDELETE https://api.kloudless.com/accounts/34
  • Response  204

Account Keys 

DEPRECATED: Instead of Account Keys, Kloudless now uses OAuth 2.0 Bearer tokens to authenticate accounts and authorize API requests. The documentation below is for reference only. Please refer to the Authentication docs for more information.

Existing Account Keys can be converted to OAuth 2.0 Tokens using the conversion endpoint below.

Deprecated endpoints

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.

Note that both Account Keys and API Keys can be used to authorize API requests to the Account Keys endpoints, similar to other endpoints.

  • 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 1 and 1000.

    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",
             }
         ]
    }

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",
     }

Delete an Account Key 

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

Deleting an account key will completely remove it, and not permit any further API requests using that Account Key.

You must provide the ID of the Account Key to delete in the URL as shown below (e.g. 20). You can retrieve the ID of the Account Key for your account by performing a request to the List Account Keys endpoint.

Example request:

curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    -XDELETE 'https://api.kloudless.com/v0/accounts/15/keys/20'
  • Response  204

Account Key -> OAuth Token 

Convert an Account Key to an OAuth 2.0 Bearer TokenPOST /accounts/{account_id}/token_from_key

Account Keys have been deprecated in favor of OAuth 2.0 Bearer Tokens, as described in the Authentication docs’ migration section. You can use this endpoint to create/retrieve the OAuth 2.0 Bearer token for the account, if the account has an Account Key associated with it.

Once you’ve obtained the OAuth 2.0 Token, please use that for future API requests. Please delete your account’s existing Account Key using the delete endpoint. This ensures that an attacker is unable to obtain an OAuth Token in the future using the Account Key.

Here is an example:

# Obtain and store the OAuth 2.0 token.
curl -XPOST -H 'Authorization: AccountKey [KEY]' -X POST \
    'https://api.kloudless.com/v0/accounts/123/token_from_key'

# The response to the request above contains the same information that
# would be provided when an access token is retrieved via the OAuth 2.0
# Authorization flow.

# Obtain the ID of the Account Key to delete.
curl -H 'Authorization: AccountKey [KEY]' \
    'https://api.kloudless.com/v0/accounts/123/keys/'

# The ID in the response's keys[0].id can be used in place of [ID] below
# to delete the Account Key.
curl -H 'Authorization: AccountKey [KEY]' -X DELETE \
    'https://api.kloudless.com/v0/accounts/123/keys/[ID]'
  • RequestToggle
  • Headers
    Authorization: AccountKey [KEY]
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "access_token": "1VMILsQTCFgbROAXxGrG2Hv6o3E",
      "token_type": "Bearer",
      "scope": "gdrive:normal.storage",
      "account_id": 123
    }

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. See the raw_id attribute for more information.

  • 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 associated with.

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

  • ancestors An object listing all the ancestor folders going back to the root folder, with the most immediate ancestor listed first. May be null if not available.

  • 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.

  • raw_id The decrypted id. Contact us at support@kloudless.com if you would like to access the raw ID.

  • owner An object with metadata on the user who owns the file. Includes the user’s id where possible. If the id differs from the one returned by the Team endpoint, both are valid for that user. May not be present if unavailable.

  • last_modifier Similar to owner, but for the user that last modified the file. May not be present if unavailable.

Upload a File 

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

You can only upload files to folders that have can_upload_files set to true. This is true for almost all folders except certain restricted folders such as the root folder in a service that does not permit file uploads to the root directory. See the Folder Resource for more information.

To upload a file, POST the binary contents of the file to this endpoint with the headers containing the name of the file as well as the ID of the folder to upload the file to.

Required Headers:

  • X-Kloudless-Metadata: A JSON string, with the attributes:
    • parent_id: The ID of the folder to upload the file to.
    • name: The name of the file being uploaded.

Here is an example, with the file name héllö.png and folder ID fL2hp:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/octet-stream'
    -H 'X-Kloudless-Metadata: {"name": "héllö.png", "parent_id": "fL2hp"}' \
    'https://api.kloudless.com/v0/accounts/123/files' \
    --data-binary @FILENAME

NOTE: Binary file uploads are limited to 100 MB. If you would like to upload files larger than this please use the multipart upload endpoint.

You can also upload files from a URL instead. To do this, send a normal POST request with a JSON string with the attributes:

  • parent_id: The ID of the Folder to upload the file to.

  • name: The name of the file being uploaded.

  • url: A URL the file can be accessed at. The response to a request to the URL must provide the size of the data being accessed in the Content-Length header.

Here is an example:

curl -X POST -H 'Authorization: Bearer [TOKEN]' \
    -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'

NOTE: Uploads via the url option can be any size and will automatically perform a multipart upload if required and supported.

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

Deprecated version: Previously, this endpoint accepted a multipart POST request that included the file data as well as other parameters such as the file name and parent ID. This has been deprecated and will be removed in the next version. For reference, the previous upload format is available here

  • Parameters
  • overwrite
    boolean (optional) Default: False 

    Specifies whether to overwrite existing files

    Choices: False True

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/octet-stream
    X-Kloudless-Metadata: {"name": "test.png", "parent_id": "fL2hp"}
    Body
    [file contents]
  • 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,
        "path": "/All Files/Test folder/test.png",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": null,
        "owner": {
            "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
        },
        "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: Bearer [TOKEN]' \
    '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,
        "path": "/All Files/Test folder/test.png",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": [
            {
                "name": "Test folder",
                "id": "fL2Hp"
            },
            {
                "name": "All Files",
                "id": "FrZekE=="
            }
        ],
        "owner": {
            "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
        },
        "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. Note that moving the file to a new location will remove the file from its previous location.

The request body may include the following optional attributes:

  • parent_id: The ID of the folder to move the file to. Include this only when moving a file to a different directory.

  • name: The new name of the file. Include this only if the file’s name is being changed.

  • account: The ID of the account to move the file to. Include this only when moving a file to an account different from the one the file currently resides in. The parent_id must also be specified.

  • user: The ID of the user whose folder the file is being moved to. Include this only if the destination account is an admin account and requires impersonation to transfer the file to the new location. User IDs may be obtained from the Team endpoint. The parent_id must also be specified. This field is required when impersonating users since the X-Kloudless-As-User header only determines the user to impersonate when accessing the file at its current location, and not the user to impersonate when transferring the file to its new location. If the users are the same, this field may be omitted.

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:

curl -X PATCH -H 'Authorization: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]
    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,
        "path": "/All Files/Test folder/new-cool-name (2).png",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": null,
        "owner": {
            "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr="
        },
        "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 100 MB, 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: Bearer [TOKEN]' \
    --data-binary @/path/to/local/file \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    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,
        "path": "/All Files/Test folder/new-cool-name (2).png",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": null,
        "owner": {
            "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr="
        },
        "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: Bearer [TOKEN]' \
    https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnXJwCg==/contents
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
  • 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 object to describe the operation that will be performed:

The request body may include the following attributes:

  • parent_id (required): The ID of the folder to copy the file to.

  • name (optional): The new name of the file. Include this only if the file’s name is being changed.

  • account (optional): The ID of the account to copy the file to. Include this only when moving a file to an account different from the one the file currently resides in.

  • user (optional): The ID of the user whose folder the file is being moved to. Include this only if the destination account is an admin account and requires impersonation to copy the file to the new location. User IDs may be obtained from the Team endpoint. This field is required when impersonating users since the X-Kloudless-As-User header only determines the user to impersonate when accessing the file at its current location, and not the user to impersonate when copying the file to its new location. If the users are the same, this field may be omitted.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -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 its metadata instead.

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    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,
        "path": "/All Files/Test folder/copied-file.png",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": null,
        "owner": {
            "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr="
        },
        "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. This feature can be used for the following services:

  • box

  • gdrive

  • sharepoint

  • onedrivebiz

  • sharefile

Some services may still provide a mechanism for users to restore the file.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' -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

Create an Upload URL for a File 

Create an Upload URL for a FilePOST /accounts/{account_id}/file_upload_url{?overwrite,expires_in,use_http}

To upload a file via the Kloudless API, please use the upload endpoint instead.

In some cases, it is preferable to have the client directly upload a file to a third-party storage service. While this is usually unnecessary, this endpoint may be used if required. Kloudless can generate a signed URL to provide to a client to upload the data to.

To create the URL, perform a POST request with a JSON object with the following attributes:

  • parent_id: The ID of the Folder to upload the file to.

  • name: The name of the file being uploaded.

Here is an example:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v0/accounts/123/file_upload_url' \
    -XPOST -d '{"parent_id":"fL2hp", "name": "test.png"}' \

The response contains the URL and the HTTP method to use to upload the binary content of the file.

This endpoint is currently available for the following services:

  • s3
  • Parameters
  • overwrite
    boolean (optional) Default: False 

    Specifies whether to overwrite existing files

    Choices: False True

    expires_in
    integer (optional) Default: 300 

    Specifies the duration of availability of the upload url.

    Choices: [1..10000]

    use_http
    boolean (optional) Default: False 

    Specifies whether the upload url should use HTTP instead of HTTPS. If a service only supports one of the protocols, this parameter will be ignored and a url using that protocol will be returned.

    Choices: False True

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
      "parent_id": "fL3Rlc3QucG5n==",
      "name": "test.png"
    }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "method": "put",
        "url": "https://s3.amazonaws.com/test.png?signature=XFOHi1bWEKD",
    }

Raw ID -> Kloudless ID 

Convert a Raw ID to a Kloudless Resource IDPOST /accounts/{account_id}/convert_id{?retrieve_metadata}

This endpoint converts IDs retrieved by connecting directly to a cloud service into a Kloudless ID usable with the Kloudless API. It is currently intended for use with file and folder IDs.

Kloudless also enables you to convert IDs in the other direction, from an encoded Kloudless ID to a raw ID you can use directly with a cloud service. See the raw_id attribute for more information.

To retrieve the Kloudless ID, perform a POST with a JSON object with the following attributes:

Here is an example:

curl -XPOST -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v0/accounts/123/convert_id' \
    --binary-data '{"raw_id": "abcsdajhsdflk-lkasjhd-123", "type": "file"}'

The response contains a usable Kloudless ID and the resource’s metadata if requested. Fetching the metadata ensures that the ID passed in is valid and that the underlying resource exists. Since requesting the metadata requires performing a request to the underlying service, you can optimize performance by skipping validation and only retrieving the ID if that is all that is needed.

  • Parameters
  • retrieve_metadata
    boolean (optional) Default: False 

    Specifies whether to retrieve the resource’s metadata or not.

    Choices: False True

  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
      "raw_id": "abcsdajhsdflk-lkasjhd-123",
      "type": "file"
    }
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "fL3Rlc3QucG5n=="
    }

List Recent Files 

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

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.

To enable access to recent file activity for accounts connected to your application, visit the App Details page and ensure the checkbox for ‘Collect Recent File data’ is checked.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    '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 1 and 1000.

    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.

    after
    ISO 8601 timestamp (optional) 

    Only files updated after this time will be returned.

  • 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,
                "path": "/All Files/Test folder/test-1.png",
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "ancestors": null,
                "owner": {
                    "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
                },
                "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,
                "path": "/All Files/Test folder/test-2.png",
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "ancestors": null,
                "owner": {
                    "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
                },
                "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,
                "path": "/All Files/test2/Test folder/test-3.png",
                "parent": {
                    "id": "fL2Hp",
                    "name": "Test folder",
                },
                "ancestors": null,
                "owner": {
                    "id": "jtadjYiSkjLbUJuIglJXRsfDF51RfQGQUNL4lekbIG3jl="
                },
                "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

  • alfresco_cloud: file name and contents

  • salesforce: file name

  • hubspot: file name

  • jive: file name

with more in the works!

The response contains the following information:

  • count Number of file objects in search results.

  • objects List of file 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: Bearer [TOKEN]' \
    '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: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    '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 1 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,
                "path": null,
                "parent": {
                    "id": "root",
                    "name": "Google Drive"
                },
                "ancestors": null,
                "owner": {
                    "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
                },
                "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,
                "path": null,
                "parent": {
                    "id": "fN2BVsAty3v2b",
                    "name": "Classics"
                },
                "ancestors": null,
                "owner": {
                    "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
                },
                "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 resumable 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.

The entire upload process is made up of three parts:

  1. Initialize the session

  2. Upload the parts

  3. Finalize the session

Currently multipart uploads are supported for the following services:

  • azure

  • s3

  • dropbox

  • egnyte

  • gdrive

  • skydrive

  • sharefile

  • sharepoint

  • onedrivebiz

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

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

Currently, parallelized multipart uploads are supported for the following services:

  • azure

  • s3

Initialize Multipart Session 

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

To begin a multipart session, POST a JSON object with the information below:

  • name: The name of the file to upload.

  • parent_id: The ID of the parent folder to upload the file to.

  • size: The total size of the file being uploaded. The services below require this information and will error if not provided:

    • gdrive
    • egnyte
    • skydrive

    Multipart Uploads to other services do not require this field.

The response will contain the following information:

  • id: The ID of the new multipart resource you will be interacting with. Use this ID to reference the session and upload parts.

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

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

  • parallel_uploads: A boolean value that determines whether the chunks can be uploaded in parallel. If false, they must be uploaded serially, in order.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -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. If False, an alternate name will be chosen for the 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,
        "parallel_uploads": true,
    }

Retrieve Multipart Session Information 

Retrieve Multipart Session InformationGET /accounts/{account_id}/multipart/{multipart_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 associated with.

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

  • parallel_uploads: A boolean value that determines whether the chunks can be uploaded in parallel. If false, they must be uploaded serially, in order.

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

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: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]' \
    -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,
        "path": "/Test folder/test-big-file.iso",
        "parent": {
            "id": "fL2Hp",
            "name": "Test folder",
        },
        "ancestors": null,
        "owner": {
            "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
        },
        "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: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]' \
    -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,
        "path": null,
        "parent": {
            "id": "root",
            "name": "Google Drive",
        },
        "ancestors": null,
    }

Retrieve Folder Metadata 

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

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
  • 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,
        "path": null,
        "parent": {
            "id": "root",
            "name": "Google Drive",
        },
        "ancestors": null,
    }

Retrieve Folder Contents 

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

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

The response contains the following information:

  • count: Integer. Number of child files/folders in this folder.

  • objects: Array. List of file/folder metadata objects.

  • page Integer/String. Identifier of the returned page.

  • next_page Integer/String. Identifier of the next page. null if no further pages available.

  • has_next Boolean. (Deprecated: see next_page instead) Whether there is a next page.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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. Page sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    recursive
    boolean (optional) Default: False 

    All files and folders within this folder will be returned if possible. Currently supported for dropbox and gdrive.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 2,
        "page": 1,
        "next_page": null,
        "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,
                "path": null,
                "parent": {
                    "id": "root",
                    "name": "Google Drive",
                },
                "ancestors": null,
    
            },
            {
                "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,
                "path": null,
                "parent": {
                    "id": "root",
                    "name": "Google Drive",
                },
                "ancestors": null,
                "owner": {
                    "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20="
                },
                "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 similarly to moving files. As mentioned in the docs for renaming/moving files, the name and/or parent_id of the new folder may be specified.

We currently do not support moving entire folders between cloud storage accounts. However, the user attribute is supported for moving folders between users within the same admin account.

See the Files endpoint for more information.

Here is an example:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' -XPATCH \
    -d '{"parent_id": "faGVycGFkZXJwZGlyCg==", "name": "New Folder Name"}' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='

The metadata of the new folder is returned.

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    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,
        "path": "/All Files/New folder/New Folder Name",
        "parent": {
            "id": "faGVycGFkZXJwZGlyCg==",
            "name": "New Folder",
        },
        "ancestors": null,
    }

Copy a Folder 

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

This endpoint is supported by the services mentioned below.

Some services require custom OAuth credentials, configurable through the developer portal, to prevent rate-limiting:

  • gdrive

  • skydrive

  • sugarsync

  • s3

  • salesforce

  • hubspot

NOTE: Response times for the above services scale with the size of the folder being copied, and currently do not succeed if the copy operation takes longer than 15 minutes to process. This is because Kloudless individually copies each file in the folder.

The following services are also supported, but do not require custom OAuth credentials as they natively support folders being copied:

  • dropbox

  • box

  • sharefile

  • evernote

  • sharepoint

  • onedrivebiz

To make a copy of the folder, you may specify the parent_id, name and user fields in a JSON object in a manner similar to the mechanism used for copying files.

We do not currently support using the account attribute to copy folders between different accounts. Using the user attribute to copy folders between users within an admin account is supported for the services listed above that natively support folders being copied (e.g. box, sharepoint, etc.).

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]
    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,
        "path": "/All Files/New Folder/Copied Folder",
        "parent": {
            "id": "fL2hp",
            "name": "New Folder",
        },
        "ancestors": null,
    }

Delete a Folder 

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

Deleting a folder can be done recursively by setting the recursive parameter to True. To delete the folder only if the folder is empty, set the recursive parameter to False.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' -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’s or folder’s permissions endpoint. Permissions objects consist of the following fields:

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

  • email The email of the user associated with this permission (if it exists).

  • name The name of the user associated with this permission (if it exists).

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

    • previewer Grants limited read access to view previews of this resource provided by the service.

    • reader Grants access to view, download, comment and link to the resource.

    • writer Grants ability to edit this resource in addition to reader access.

    • 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

  • dropbox

  • sharepoint (only read access, at the current time)

  • onedrivebiz (only read access, at the current time)

NOTE: Each service has its 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: Bearer [TOKEN]' \
    '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",
          "name": "Test User",
          "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: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]
    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",
          "name": "Test Writer",
          "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: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]
    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",
          "name": "Test Writer",
          "role": "writer"
        },
        {
          "id": 211581041,
          "email": "previewer@test.com",
          "name": "Test Previewer",
          "role": "previewer"
        }
      ]
    }

Properties 

Properties allow custom metadata to be set on files. This is done by defining key-value pairs for each file.

Properties are stored in Kloudless unless the service the file resides in supports custom attributes on files. In that case, Kloudless will send commands to set, retrieve and update properties to the service instead and not store any properties at the Kloudless level. This is the case for the following services:

  • box

  • gdrive

  • sharefile (coming soon)

  • evernote (coming soon)

  • azure (coming soon)

Properties for all other services are stored by Kloudless.

Property objects consist of the following fields:

  • key User-defined string.

  • value User-defined string.

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

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

Files in box have the following additional attributes:

  • box_scope Box scope associated with this file. Default: global

  • box_template Box template associated with this file. Default: properties

List Properties 

List propertiesGET /accounts/{account_id}/files/{file_id}/properties

Retrieves all properties for a given file.

The response contains the following information:

  • properties A list of user-defined properties belonging to this file. Each object contains information as described in Properties above.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/files/fTmV3IEZvbGRlcg==/properties'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "properties": [
        {
          "key": "department",
          "value": "engineering",
          "created": "2015-03-17T20:42:18.627533Z",
          "modified": "2015-03-17T20:42:18.627533Z"
        },
        {
          "key": "readonly",
          "value": "true",
          "created": "2015-03-17T20:42:18.627533Z",
          "modified": "2015-03-17T20:42:18.627533Z"
        }
      ]
    }

Update Properties 

Update propertiesPATCH /accounts/{account_id}/files/{file_id}/properties

Update, add, or delete one or more properties for a given file.

The request body should be a list of objects consisting of key-value pairs. Specifying a property with the value null will delete that property.

Example request body:

[
    {
        "key": "department", # updates property (assuming it already exists)
        "value": "marketing"
    },
    {
        "key": "readonly", # deletes property
        "value": null
    },
    {
        "key": "category", # adds property (assuming it does not already exist)
        "value": "sales"
    }
]

NOTE: For Box files, you can additionally specify a box_scope and box_template with each key-value pair. These two fields default to global and properties , respectively.

The response contains the following information:

  • properties A list of user-defined properties belonging to this file. Each object contains information as described in Properties above.

Example request (using the above request body):

curl -X PATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '[{"key": "department", "value": "marketing"},
        {"key": "readonly", "value": null},
        {"key": "category", "value": "sales"}]' \
    'https://api.kloudless.com/v0/accounts/123/files/fTmV3IEZvbGRlcg==/properties'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "properties": [
        {
          "key": "department",
          "value": "marketing",
          "created": "2015-03-17T20:42:18.627533Z",
          "modified": "2015-07-16T22:49:55.984Z"
        },
        {
          "key": "category",
          "value": "sales",
          "created": "2015-07-16T22:49:55.984Z",
          "modified": "2015-07-16T22:49:55.984Z"
        }
      ]
    }

Delete all Properties 

Delete all PropertiesDELETE /accounts/{account_id}/files/{file_id}/properties

Deletes all properties for a given file.

Example request:

curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/files/fTmV3IEZvbGRlcg==/properties'
  • Response  204

Links 

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 object with these attributes:

  • file_id The ID of the file to link to.

In addition, the following optional attributes 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. See Link attribute docs above for more information on direct.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -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: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "fMEI0H4PP5", "direct": true}' \
    'https://api.kloudless.com/v0/accounts/15/links'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    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://kloudl.es/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. 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([API Key], [request contents]))

For applications with multiple API Keys, the API Key used in the signature will be the oldest one available.

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, modifying, or deleting resources generate events that we track. They are represented as a stream of event objects.

To enable access to event data for accounts connected to your application, visit the App Details page and ensure the checkbox for ‘Collect Events’ is checked.

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

  • copy: a resource has been copied

  • restore: a resource has been restored after being deleted

We will return the most specific event where possible; otherwise, we will return the event specified by the underlying service.

You can find the list of Kloudless Enterprise events here.

Event objects have the following fields:

  • id (deprecated): 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 (deprecated): Either + or - indicating what was done to the file. This will be removed 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

  • ip: User’s IP Address, if available. May be null.

  • 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:

  • alfresco

  • alfresco_cloud

  • box

  • cmis

  • cq5

  • dropbox

  • egnyte

  • evernote

  • gdrive

  • hubspot

  • jive

  • onedrivebiz

  • s3

  • salesforce

  • sharefile

  • sharepoint

  • skydrive

  • smb

  • webdav

Admin accounts for certain services provide org-wide file-system events for all users in the organization in Kloudless’s Enterprise version:

  • box

  • gdrive

  • egnyte

  • sharepoint

  • onedrivebiz

Event data may not be updated right away. Latency prior to an update varies in the cloud version and is detailed below, but is configurable in self-hosted/private Kloudless Enterprise installations.

The following services notify Kloudless of changes to users’ accounts, with event data updated in at most 1.5 minutes:

  • box

  • dropbox

  • evernote

  • gdrive

  • s3 New buckets are detected every 20 min. Buckets with existing Event Configurations will be ignored.

  • smb

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:

  • cq5

  • egnyte

  • hubspot

  • jive

  • onedrivebiz

  • salesforce

  • sharefile

  • sharepoint

  • skydrive

  • webdav

The CMIS-like services listed below also poll for changes. To enable more efficient retrieval of events by Kloudless, please configure the repository to create a change log if possible.

  • alfresco

  • alfresco_cloud

  • cmis

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.

List Events 

list eventsGET /accounts/{account_id}/events{?cursor,page_size}

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 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.

  • remaining: Number of events remaining in the stream.

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: Bearer [TOKEN]' \
    '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.

    page_size
    number (optional) Default: 1000 

    Number of events in the stream to return, if available. The page_size must be greater than or equal to 1 and less than or equal to 1000.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "cursor": 330,
      "count": 3,
      "remaining": 0,
      "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"
            },
            "ancestors": null,
            "owner": {
                "id": "n1nNjHU4FP37p2VEmtZqmLQFN4BydJwiPV5YdiSqO="
            },
            "created": null,
            "modified": "2015-10-02T21:38:03Z",
            "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"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:41Z",
            "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"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:45Z",
            "path": "/Shared Documents/test (2).png"
          },
          "action": "-",
          "account": 613076,
          "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
          "event_id": 330,
          "user_id": null,
          "type": "delete",
          "previous_metadata": {},
        }
      ]
    }

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 initial request.

This returns a dictionary with a single field:

  • cursor: The most recent cursor for this account

Example Request:

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

Enterprise Events 

If you are using Kloudless Enterprise, we offer the following events for administrator accounts:

  • login: A user successfully logged into the account

  • login_failed: A user failed to log into the account

  • share_link: A link to a resource was shared

  • unshare_link: A link to a resource was unshared

  • collaboration_add: A collaborator was added to a resource

  • collaboration_invite: A collaborator was invited to a resource

  • collaboration_accept: A collaborator has accepted the invite to a resource

  • collaboration_delete: A collaborator was removed from a resource

  • collaboration_update: The resource’s collaborators were updated

  • user_invite: A user has been invited

  • user_add: A new user was created

  • user_delete: A user was deleted

  • user_update: A user was updated

  • group_add: A new group was created

  • group_delete: A group was deleted

  • group_update: A group was updated

  • group_add_user: A user was added to a group

  • group_delete_user: A user was removed from a group

Enterprise Event objects may also have the fields below in lieu of metadata and previous_metadata. They may either not be present or default to {} where unavailable or not applicable.

  • user: Information on the user associated with the event. e.g.: The user that was created, or the user a file was shared with.

  • previous_user: The previous user data that was modified.

  • group: Information on the group associated with the event.

  • previous_group: The previous group data that was modified.

  • link: Metadata on a shared link. Includes the link’s URL.

  • login: Metadata on a login or attempted login.

  • collaboration: Metadata on a collaboration

See the Team endpoint for more information on user and group objects.

NOTE: Enterprise events can be retrieved through the normal events endpoint, and will appear for administrator accounts for the following services:

  • box

  • onedrivebiz

  • sharepoint


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.

The following services require user impersonation via X-Kloudless-As-User to access that user’s data via an admin account:

  • dropbox

  • box

  • onedrivebiz

  • gdrive

Other services such as sharepoint do not require, nor allow, users to be impersonated as all data is already available in a shared location.

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.

    • type Always ‘user’.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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 sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    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",
                "type": "user",
            },
        ],
    }

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.

  • type Always ‘user’.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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",
        "type": "user",
    }

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.
    • type Always ‘group’.

    • email An email associated with the group, if any. Not present if unavailable.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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",
                "type": "group",
            },
        ],
    }

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.

    • type Always ‘group’.

    • email An email associated with the group, if any. Not present if unavailable.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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 sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    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",
                "type": "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.

  • type Always ‘group’.

  • email An email associated with the group, if any. Not present if unavailable.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/groups/g982734'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": "g982734",
        "name": "Test Group",
        "type": "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.

    • type Always ‘user’.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    '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 sizes are treated as advisory. If a page_size is outside the range supported by a service, the closest supported value will be used.

    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",
                "type": "user",
            },
        ],
    }

Rate-Limiting 

A default rate-limit of 10 requests/account/second is present for all accounts connected to your application. Please contact us if this limit is insufficient. Third-party services may set rate-limits as well.


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 here.