Back to top

Introduction 

Add multiple software 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 Application ID to get started. Get one for free by signing up!

Connecting user accounts 

Your application can prompt a user to connect an account for a software service to obtain access to that service (e.g. Google Drive).

Please refer to the Authentication docs for more information on connecting user accounts to your Kloudless application, as well as which APIs each service makes available.

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 v1. You can switch versions via the menu at the top of this page.

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

Please refer to the Developer Portal’s Walkthrough for examples of connecting accounts and performing API requests.

Supported Services 

The currently supported services for each API category are included below with their service identifiers. The service identifier is used to refer to that service within the Kloudless API. Note that some services may provide access to multiple APIs. See our Authentication docs for more information on connecting accounts to your application.

  • File Storage Services

    • 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 Files: salesforce
    • HubSpot Files: hubspot
    • SMB: smb
    • Jive: jive
    • WebDAV: webdav
    • Adobe CQ5: cq5
    • FTP: ftp
  • Object Storage Services

    • Amazon S3: s3
    • Azure Storage: azure
  • CRM Services

    • Salesforce CRM: salesforce
    • Microsoft Dynamics: dynamics
    • Oracle Sales Cloud: oracle
    • Pipeliner CRM: pipeliner
    • Zoho CRM: zoho
    • HubSpot CRM: hubspot
    • SugarCRM: sugarcrm
  • Calendar Services

    • Google Calendar google_calendar
    • Outlook Calendar outlook_calendar
    • CalDAV caldav
  • Audit Services

    • AWS CloudTrail cloudtrail
    • Azure Resource Manager azurerm

Accessing the Kloudless APIs 

The navigation bar at the top of this page provides a full list of APIs that Kloudless makes available. After a user connects an account to your application, your application can make requests to API endpoints to retrieve or modify data in the user’s account.


Interactive Docs 

Once you have reviewed our API documentation, you can test out API requests by using your App ID and API Key in our Interactive Docs.

Visit our Interactive Docs to give it a try!


API-wide options 

Headers can be used to alter the behavior of the API where supported.

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

Sending additional raw headers 

Requests that require additional headers to be forwarded to the upstream service can specify them via the X-Kloudless-Raw-Headers header. These headers will be sent when Kloudless performs requests to the upstream service to fulfil the API request.

The value of the X-Kloudless-Raw-Headers header should be a JSON object where each key-value pair represents an additional header’s name and value respectively.

For example, to send the header Box-Notifications: off, specify X-Kloudless-Raw-Headers: {"Box-Notifications": "off"}.

The following services support sending additional raw headers:

  • box

  • skydrive

  • sharefile

  • sugarsync

  • egnyte

  • sharepoint

  • onedrivebiz

  • salesforce

  • hubspot

  • jive

  • dynamics

  • oracle

  • outlook_calendar

Impersonating a user 

API requests to Admin accounts can include the X-Kloudless-As-User: USER_ID to access or modify data for individual user accounts within an organization. Please refer to the Team API for more information.


Object and API types 

Objects provided in responses from the Kloudless API include two attributes that describe the type of object:

  • api This corresponds to the API category associated with the data represented by the object. For example, the Storage, or Events API.

  • type This corresponds to the type of object within that API category.

Data available from software service accounts can span multiple APIs and object types. For example, gdrive provides access to event data via the events API, and storage data via the storage API.

Here is a full list of available API types:

Here are common object types present in all APIs:

  • object_list This is a list of objects, each of which could be of any type and belong to any API.

Refer to individual API pages for more information on object types available in each API.


Raw Data and the Pass-through API 

Raw Data 

Raw data provided by the upstream service in response to API requests can be accessed in the response Kloudless provides. See the X-Kloudless-Raw-Data header option for more information.

The raw attribute in response objects will contain the following attributes:

  • object The raw data received from the third-party service.

  • id (optional) This is the decoded representation of the Kloudless object’s ID for objects that include an encoded Kloudless ID, such as Files.

Pass-through API

The Pass-through API endpoint enables your application to access the full functionality of supported services regardless of which endpoints Kloudless supports. Your application can request Kloudless to perform a request to any URL in the upstream service. Kloudless continues to ensure any default values such as authorization headers are correctly added to your request.

Pass-through API 

Perform arbitrary API requestsPOST /accounts/{account_id}/raw

To perform a pass-through API request, send a POST request to this Kloudless API endpoint. Indicate the URL you would like Kloudless to make the request to and the HTTP method to use by including the following headers with your request:

  • X-Kloudless-Raw-URI: The target path or URL in the upstream service.

    If only the path is provided, Kloudless will fill in the default domain to send the API request to. If it is not clear which domain should be used or you prefer to guarantee which domain is accessed, include the full URL to perform the API request to instead. Please note that the URI is validated against a white-list of domains that are permitted to perform API requests to.

  • X-Kloudless-Raw-Method: The HTTP method to use. e.g. GET, POST, PROPFIND, etc.

The Authorization header should still include the Kloudless account’s OAuth 2.0 Bearer token or your Kloudless application’s API Key, as with any other API request to the account. Kloudless will alter appropriate headers to correctly authenticate the request to the third-party service.

The following optional headers will also correctly be considered by Kloudless rather than passed through to the upstream service:

The body of the request as well as any other headers included will be sent to the upstream service in the same format received. There are no limits to the size of the request or response as Kloudless streams both in memory.

The following services are currently supported:

  • box

  • dropbox

  • egnyte

  • gdrive

  • salesforce

  • sharepoint

  • onedrivebiz

  • sharefile

  • caldav

  • sugarcrm

Here is an example of a pass-through API request to the Google Drive API:

curl -XPOST 'Authorization: Bearer [TOKEN]' \
    -H 'X-Kloudless-Raw-URI: /drive/v2/about'
    -H 'X-Kloudless-Raw-Method: GET' \
    'https://api.kloudless.com/v1/accounts/123/raw' \

Above, X-Kloudless-Raw-URI could also be specified using the full URL https://www.googleapis.com/drive/v2/about.

NOTE: The body content of the HTTP request should match the requirements of the request to the target upstream API endpoint. An API request to Dropbox that uses data in the body is provided as an example in the Request and Response sections below.

  • RequestToggle
  • Headers
    Authorization: Bearer [Token]
    Content-Type: text/plain; charset=dropbox-cors-hack
    X-Kloudless-Raw-URI: https://api.dropboxapi.com/2/files/list_folder
    X-Kloudless-Raw-Method: POST
    Body
    {
        path : ""
    }
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "entries": [
        {
          ".tag": "folder",
          "name": "Kloudless",
          "path_lower": "/kloudless",
          "path_display": "/Kloudless",
          "id": "id:XxYyZz12345"
        }
      ],
      "cursor": "XxYyZz12345",
      "has_more": false
    }

Raw Data -> Kloudless ID 

Convert Raw data to a Kloudless Resource IDPOST /accounts/{account_id}/encode_raw_id

Kloudless Object IDs are symmetrically encrypted by Kloudless prior to being provided via the API. This encoding ensures that IDs can always be treated as arbitrary strings. The encryption further guarantees that malicious users are less likely to be able to guess or provide an expected ID to the API.

In some scenarios, the decrypted raw ID may be required. These raw IDs may not be used for API requests to the Kloudless API, but may be useful for API requests directly to the third-party cloud service, such as Dropbox.

A raw ID can be converted to a Kloudless Object ID by using this endpoint. This enables API requests to a service via the Kloudless API, if the ID of an object in that service is already known.

For most services, the decrypted ID is the ID provided by that service’s API. In this case, the only information required to generate the Kloudless Object ID would be the object’s raw ID, provided via the id attribute. Any minor variations, such as a trailing slash suffixed for S3, will be documented.

For some services, more information is required, such as the object type. These requirements are described below. The raw ID provided by the service is referred to as raw_id.

The id attribute also accepts the following special IDs:

  • root: The root folder.

  • trash: The Trash, Recycle Bin or equivalent.

To retrieve a Kloudless Object ID, perform a POST request with a JSON object containing the attributes required for the specific service the raw ID belongs to. If the service is not specified in the list below, the only attribute required is id.

Example of the default process:

curl -X POST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/4514/encode_raw_id' \
    --data-binary '{"id": "abcsdajhsdflk-lkasjhd-123"}'

Here are additional attributes required for some services:

  • alfresco: See cmis below.

  • alfresco_cloud: See alfresco.

  • azure:

    • container_name: Name of container.
    • id: Object path within container.
  • cmis:

    • repository_id: CMIS Repository ID.
    • id: ID of object.
  • dropbox:

    • id: ID of the Dropbox file/folder.
    • shared: Optional; for a Shared Folder, set it to true.
  • documentum: See cmis.

  • evernote:

    • object_type: Type of Evernote item. Valid values are:
      • attachment
      • notebook
      • note
      • enml
  • filenet: See cmis.

  • gdrive: Special values for id:

    • shared: The “Shared with Me” folder.
  • s3:

    • bucket_name: S3 bucket ID.
    • id: Object path.
  • salesforce:

    • object_type: Type of object. Valid values are:
      • chatter_file
      • chatter_folder
      • content_document
      • content_workspace
      • folder
      • document
      • attachment
    • id: ID of object.
  • sharepoint:

    • site_path: The path to the SharePoint site collection or sub-site.
    • list_id: An optional ID of the List containing the File/Folder Item.
    • id: A URL fragment that can be used to obtain the object.

    The id may have special values:

    • site-contents: Refers to the Site Contents of that site.
    • trash: Refers to the Recycle Bin for that site.
  • skydrive: Special values for id:

    • me/skydrive: The root folder.
    • me/skydrive/shared: The Shared folder.
  • jive:

    • object_type: Type of object. Valid values are:
      • document
      • attachment
      • file
    • entity_id: ID used with the type of content entity (file/document/attachment).
    • id: The absolute unique ID.
  • smb:

    • share_name: Name of share.
    • id: Object path.
  • onedrivebiz: See sharepoint.

Here is an example:

curl -XPOST -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/4514/encode_raw_id' \
    --data-binary '{"id": "abcsdajhsdflk-lkasjhd-123", "object_type": "notebook"}'

The response contains a usable Kloudless ID.

  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
      "id": "abcsdajhsdflk-lkasjhd-123",
      "object_type": "notebook"
    }
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "FDYfhzNjFPJIvKYmXdGWqqXfLs8NkgUOekOFp7CakJLM=",
      "api": "meta",
      "type": "kloudless_id"
    }

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:

Retrieve Task StatusGET /accounts/{account_id}/tasks/{id}

The task object has the following attributes:

  • id: identifier used to reference task in the Task endpoint.

  • status: Current status of the request, one of:

    • PENDING: The task state is unknown.
    • RECIEVED: The task was recieved, waiting to start.
    • STARTED: The task was started and currently is in progress.

Once the task has completed, the result of the request will be returned instead of the task metadata.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/15/tasks/8e3938f9-dde7-4a57-b9a2-7ad282461073'
  • RequestToggle
  • Headers
    Authorization: Bearer [Token]
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "8e3938f9-dde7-4a57-b9a2-7ad282461073",
      "status": "STARTED"
    }

Error Handling 

Kloudless unifies error responses into a common format prior to propagating them to your application.

How Kloudless handles errors 

If Kloudless encounters a server error by the upstream service, such as a response with status code over 499, Kloudless will automatically retry the API request. Kloudless will also retry requests if a token or credential must be refreshed since it had expired when the request was made.

However, if Kloudless encounters any other type of error that the service indicates is the client’s fault, such as a response with status code between 400 and 499, then Kloudless will marshall the error into the format described below and return it to the client.

Kloudless will not automatically retry requests that fail due to being rate-limited by the upstream service. Any relevant headers indicating the appropriate back-off time will be returned as described in Retry-After below.

Rate-Limiting by Kloudless 

In addition to potential rate-limiting by the upstream service, Kloudless also enforces a default rate-limit of 10 requests per connected cloud account per second. Please contact us if this limit is insufficient.

Error Message Format 

The status code of an error, along with it’s JSON content, helps identify the type of error that occurred. A description of attributes present in an error returned from Kloudless is provided below.

Attributes always present:

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

  • message: A description of the error.

  • status_code: HTTP status code of the response.

Attributes present if available:

  • id: A unique GUID for the API request.

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

Headers present if applicable:

  • Retry-After: If the error is due to rate limiting, this provides the time in seconds to wait before retrying the request. If the upstream service does not provide this information, this header will not be present. The status code for this error response will be 429.

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 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 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.
timed_out 408 The request timed out since the client did not complete the request in time.
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 service.
bad_gateway 502 Kloudless received an invalid response from the upstream service.
service_not_available 503 The upstream service is unavailable.
gateway_timeout 504 The upstream service is unavailable.
insufficient_storage 507 There is not enough free space in the account to complete the request.

* Contact us at support@kloudless.com for error resolution. Please provide the entire error received.


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.


Getting Help 

If you require assistance, please feel free to contact us at support@kloudless.com, or by opening an issue in the relevant GitHub repository or on Stack Overflow.