Update to the latest version 

This documentation is for v0 of the API and preserved for reference purposes. Support for v0 will be removed on February 28, 2018.

Access the documentation for the latest version of the Kloudless API here.

Access the migration guide for more information on updating to v1 here.

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!

Related APIs ¶

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

API Explorer 

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

Visit our API Explorer to give it a try!

Connecting user accounts 

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

Performing API requests 

Please refer to the Authorization section of the Authentication docs for more information on authorizing your app’s API requests to Kloudless.

The root URL of the API server that all API requests will be made to is https://api.kloudless.com. API requests also include the version of the API you are accessing in the URL. This documentation is for v0.

The full base URL is therefore https://api.kloudless.com/v0

Please refer to the Developer Portal’s Walkthrough for examples of connecting accounts and performing 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.

• 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 credentials Kloudless uses to connect to the underlying third-party account. This is useful for direct requests to a service’s API, bypassing Kloudless. The following attributes can be added to the account metadata:

• token The third-party account’s token/key/secret, that is used by Kloudless to access the account. Kloudless automatically refreshes OAuth 2.0 tokens if necessary.

• token_secret The OAuth 2.0 token secret, if any.

• account_id The third-party account’s ID. This is useful when determining how to construct independent requests directly to a third-party service’s API. "me" can be used as an alias for the account_id when making request with a Bearer Token and not an API Key, since Bearer Tokens uniquely identify an account.

• token_expiry ISO 8601 timestamp indicating when the token used to access the cloud 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.

List Accounts 

Import an Account 

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/'

Retrieve an Account 

Update an Account 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": false}' \
    'https://api.kloudless.com/v0/accounts/15'

Delete an Account 

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

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 

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

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

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

Retrieve an Account Key 

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

Delete an Account Key 

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

Account Key -> OAuth Token 

# 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]'

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. The encrypted string is then base-64 encoded in a URL-safe manner. This value increases in length proportionally with the cloud storage’s file ID but will not exceed 8192 characters. Some services like WebDAV 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.

• raw The raw data retrieved from the service.

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

• creator Similar to owner, but for the user that originally created the file. 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 

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

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'

Retrieve File metadata 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='

Rename/Move a File 

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=='

Update File content 

curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
    --data-binary @/path/to/local/file \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='

Download a File 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnXJwCg==/contents'

Download a Thumbnail for a File 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnXJwCg/thumbnail/?size=400'

Copy a File 

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'

Delete a File 

curl -L -H 'Authorization: Bearer [TOKEN]' -XDELETE \
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='

Create an Upload URL for a File 

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

Raw ID -> Kloudless ID 

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

List Recent Files 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/recent'

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v0/accounts/123,456,789/recent'

Search 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/search?q=hello+world'

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v0/accounts/123,456,789/search?q=hello+world'

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

• autodesk

• 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 

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'

Retrieve Multipart Session Information 

Upload Part 

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'

Finalize Multipart Session 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XPOST 'https://api.kloudless.com/v0/accounts/123/multipart/543/complete'

Abort Multipart Session 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v0/accounts/123/multipart/543'

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.

• can_list_recursively: Indicates if the contents of this folder can be listed recursively.

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

Create a Folder 

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'

Retrieve Folder Metadata 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='

Retrieve Folder Contents 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/contents'

Rename/Move a Folder 

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=='

Copy a Folder 

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'

Delete a Folder 

curl -H 'Authorization: Bearer [TOKEN]' -XDELETE \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='

Permissions 

The Permissions endpoints allow you to retrieve, grant and revoke access to files or folders in an account. Requests are performed to either the files or folders permissions endpoint. A permission object is either the user or group the permission is assigned to, or a custom object representing the permission’s properties. Each object has the following attributes:

• type The type of assignee: user, group, or representative of the type in the third-party service.

• id The assignee’s ID or the underlying service’s permission identifier if available.

• email The assignee’s email address if available.

• name The assignee’s name.

• role The assignee’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.

An approximate role is provided if an exact match is unavailable. Please retrieve the object’s raw data for more granular service-specific information.

Supported services differ in availability of permission data. Services currently supported are:

• box

  • Supports shared folders.

• gdrive

  • Supports shared files and folders.

• dropbox

  • Supports shared folders.

• sharepoint

  • Supports shared files and folders.
  • Currently supports only retrieval and unsharing of all permissions.

• onedrivebiz

  • Supports shared files and folders.
  • Currently supports only retrieval and unsharing of all permissions.

List Permissions 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/permissions'

Set Permissions 

[
    {
        "type": "user",
        "email": "reader@test.com",
        "role": "reader"
    },
    {
        "type": "user",
        "id": "uGWK298eguSG2==",
        "role": "writer"
   }
]

curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '[{"type": "user", "id": "uGWK298eguSG2==", "role": "writer"}]'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'

Update Permissions 

[
    {
        "type": "user",
        "email": "reader@test.com",
        "role": "reader"
    },
    {
        "type": "user",
        "id": "uGWK298eguSG2==",
        "role": "writer"
   },
   {
        "type": "group",
        "id": "gNTQ==",
        "role": ""
   }
]

curl -XPATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '[{"type": "user", "id": "uEZEKdS4Webxw==", "role": "writer"}, {"type": "group", "id": "gNTQ==", "role": ""}]'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'

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 

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

Update Properties 

[
    {
        "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"
    }
]

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'

Delete all Properties 

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

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.

List Links 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/15/links'

curl -L -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v0/accounts/15,16,17/links'

Create a Link 

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'

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "fMEI0H4PP5", "direct": true}' \
    'https://api.kloudless.com/v0/accounts/15/links'

Retrieve a Link 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/15/links/aZ9APHB0OrTTP74ia9xc'

Update a Link 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d "{\"active\": false, \"expiration\": \"$(date -v'+1d' -u +'%Y-%m-%dT%H:%M:%SZ')\"}"
    'https://api.kloudless.com/v0/accounts/15/links/aZ9APHB0OrTTP74ia9xc'

Delete a Link 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE \
    'https://api.kloudless.com/v0/accounts/15/links/aZ9APHB0OrTTP74ia9xc'

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. Will be null if unavailable.

• 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 _{Buckets with existing Event Configurations will be ignored.}

• salesforce

• sharefile

• sharepoint _{Only the primary site collection’s Document Library will be tracked in our cloud version. Kloudless Enterprise tracks data in all site collections.}

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

• 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 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/events?cursor=121'

Retrieve Latest Cursor 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/events/latest'

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 shared link to a resource was removed

• share_update: A shared link to a resource was modified

• 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

• view: The resource was viewed

• download: The resource was downloaded

• 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 and egnyte do not require, nor allow, users to be impersonated as all data is already available to admin users.

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

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

List Users 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/users'

Retrieve a User 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/users/u4806226'

List a User's Group Memberships 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/users/u4806226/memberships'

List Groups 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/groups'

Retrieve a Group 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/groups/g982734'

List a Group's Members 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/team/groups/g982734/members'

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.

Accessing raw data 

The X-Kloudless-Raw-Data: true header can be included in requests to have the raw data from the third-party service included in the response where available. Contact us at support@kloudless.com if you would like to enable this feature for your application.

The raw data will be included as a JSON object for the key raw in the objects for which it is available. For example, the File object.

Asynchronous Requests and the Task API 

Asynchronous Requests 

The X-Kloudless-Async: true header can be included in requests to certain endpoints to allow the client to not wait for the result. Instead, a response with 202 ACCEPTED as the status code and a task object in the body will be returned. The ID from the task object used to query the status of the request and retrieve the result. The following endpoints currently support asynchronous requests:

• URL based file uploads

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/15/tasks/8e3938f9-dde7-4a57-b9a2-7ad282461073'

Errors 

Error Code Table ¶

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

• JavaScript

• Python

• Ruby

• Java

• Android

• iOS

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 Picker ¶

The File Picker 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-picker

Also check out our JSFiddle example of the File Picker.

Example Apps 

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

• https://github.com/vinodc/cloud-text-editor

  Uses the JS Authenticator library and the Python SDK

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.