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
    • SugarSync: sugarsync
    • Egnyte: egnyte
    • Evernote: evernote
    • SharePoint Online: sharepoint
    • SharePoint 2013+: sharepoint2013
    • OneDrive for Business: onedrivebiz
    • CMIS: cmis
    • Alfresco: alfresco
    • Alfresco Cloud: alfresco_cloud
    • SMB: smb
    • Jive: jive
    • WebDAV: webdav
    • Adobe CQ5: cq5
    • FTP: ftp
    • File data from other connector categories (billing plan may require the category)
      • Salesforce Files (CRM): salesforce
      • Hubspot Files (CRM): hubspot
      • Slack Files (Messaging): slack
      • Construction documents, images and drawings
        • Procore: procore
          • Drawings are read-only (listing folder contents, downloading drawing PDFs)
        • PlanGrid: plangrid
        • Autodesk: autodesk
        • Bluebeam: bluebeam
  • Object Storage Services

    • Amazon S3: s3
    • Azure Storage: azure
    • Amazon S3 compatible: s3_compatible
      • Examples: Google Cloud Storage (Interop API), Wasabi, Minio, and others.
  • 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
    • Exchange Server 2013+: exchange
    • iCloud Calendar: icloud_calendar
  • ITSM Services

    • ServiceNow: servicenow
  • 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.


API Explorer 

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

Visit our API Explorer to give it a try!


API-wide options 

Request 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 raw data 

Some connectors support sending raw data in a similar format to that received while creating or updating an object. This enables attributes specific to a particular service to be sent along with the usual unified API request without having to make an entirely raw Pass-through request. The benefits of the unified API are still preserved for the rest of the object in this manner.

Please refer to the documentation for the specific endpoint you’d like to send raw data to to confirm it supports the raw attribute. Check out CRM Account creation for an example.

Sending raw query parameters 

Raw query parameters can be passed through to upstream services by setting raw[query_name]=query_value in the query string. This helps include additional query parameters in API requests Kloudless makes to third-party services when your application makes an API request to Kloudless.

For example, include the query parameter raw[order-by]=name in an API request to Kloudless if you would like Kloudless’ API requests to include the query parameter order-by=name.

Here is another example request along with the raw query parameter, fields, for Box service.

curl -g -X GET \
    -H 'Authorization: Bearer tqcx6Iy1rj1pwJwWPbDDiqXS_SkIhDwn2XYUlxPj96HFOXbZ' \
    'https://api.kloudless.com/v1/accounts/me/storage/folders/root/contents?raw[fields]=type,name,id,size,path_collection,modified_at,created_at,parent,owned_by,created_by,modified_by,content_created_at,content_modified_at'

Remember to pass the -g option to switch off the “URL globbing parser” so you can specify URLs that contain the letters [].

This is supported for the same services that support sending raw headers (see below).

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.

Formatting JSON Responses 

By default, all JSON responses from the Kloudless API will be formatted using two spaces for each indent level. You can disable this by setting the Accept header in API requests to application/json;indent=0. This provides minor improvements to efficiency due to the reduced API response size. You can also set the indent value to a number other than 0 to include that many number of spaces for each indent level in the API response.


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 Activity 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 activity 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

  • icloud_calendar

  • sugarcrm

  • dynamics

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.

The API sometimes returns raw decoded IDs from upstream services, such as when requesting raw data, or using the pass-through API. These IDs may also be retrieved by querying the upstream API directly.

Convert raw IDs to Kloudless Object IDs first using this endpoint prior to using the ID in an API request. This allows the Kloudless API to accept the object identifier.

For most services, the decrypted ID is the ID provided by that service’s API. In this case, the only identification 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 suffix for S3, will be documented below.

Here are the attributes to send to this endpoint:

  • id: An object’s decoded upstream ID.

  • api: The object’s Kloudless API category. Defaults to storage.

  • type: The object’s Kloudless Type. Options currently include object, user, group. Most IDs have the type object unless they correspond to a specific type mentioned here, such as user. Defaults to object.

  • Any extra attributes documented below that are specific to this service.

The Kloudless API also returns the api and type in all objects that include an id. You can determine them along with an object’s raw ID by retrieving raw data with X-Kloudless-Raw-Data: true and checking raw -> object -> id for the ID.

Alternatively, the fully assembled ID that Kloudless encodes is available at raw -> id. This string can be provided directly to the API to encode by using the raw_id instead of the id. This is most valuable when objects identified via raw data in Kloudless API responses need to be used with the unified Kloudless API.

Here is an example that uses an id:

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": "abc-123", "api": "storage", "type": "object"}'

The id attribute also accepts the following special IDs:

  • root: The root folder. Only applicable to the storage API.

  • trash: The Trash, Recycle Bin or equivalent. Also intended for the storage API.

Here is an example that uses a raw_id:

curl -X POST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/4514/encode_raw_id' \
    --data-binary '{"raw_id": "!abc-123:notebook", "api": "storage", "type": "object"}'

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, s3_compatible:

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

    object type:

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

    group type:

    • site_path: Same as above.
    • resource_type: The group’s type. May be group or directoryRole. Defaults to group if not provided.
    • id: The group ID to encode.

    user type:

    • userPrincipalName: The user’s login email.
    • id: The user ID to encode.
  • skydrive: Special values for id:

    • me/skydrive: The root folder.
    • me/skydrive/shared: The Shared folder.
  • slack: Special values for id:

    • message IDs should be the UNIX timestamp of the message instead of the Slack Message ID provided as a string.
    • conversation When connecting as admin, IDs should be the composition of team ID and channel ID in format team::.
  • 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 another example that includes an extra attribute to encode an Evernote ID:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/4514/encode_raw_id' \
    --data-binary '{
      "id": "abc-123",
      "object_type": "notebook",
      "api": "storage",
      "type": "object"
    }'

The response contains a Kloudless ID that can be used with the API.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
        "id": "abc-123",
        "object_type": "notebook",
        "api": "storage",
        "type": "object",
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FDYfhzNjFPJIvKYmXdGWqqXfLs8NkgUOekOFp7CakJLM=",
      "api": "storage",
      "type": "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:

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.
data_conflict 409 Data already exists. Checking the message parameter for the reason.
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.


Tools 

Postman 

Check out our blog post for how to connect accounts and make API requests via our Postman collection.

Run in Postman

SDKs 

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.