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
    • SharePoint Online: sharepoint
    • OneDrive for Business: onedrivebiz
    • Citrix Sharefile: sharefile
    • Egnyte: egnyte
    • Evernote: evernote
    • Jive: jive
    • SugarSync: sugarsync
    • WebDAV: webdav
    • CMIS: cmis
    • SMB: smb
    • FTP(S): ftp
    • SFTP: sftp
    • Alfresco: alfresco
    • Alfresco Cloud: alfresco_cloud
    • Adobe Experience Manager: cq5
    • SharePoint 2013+: sharepoint2013
  • Object Storage Services

    • Amazon S3: s3
    • Azure Blob Storage: azure
    • Amazon S3 compatible: s3_compatible
      • Examples: Google Cloud Storage (Interop API), Wasabi, Minio, and others.
    • Alibaba Cloud OSS: aliyun_oss
  • File data from other connector categories (billing plan requires the additional category or connectors)

    • CRM
      • Salesforce Files: salesforce
      • Hubspot Files: hubspot
      • SAVO: savo
    • Chat
    • Construction documents, images, and drawings
      • Procore: procore
        • Drawings are read-only i.e. list folder contents and download drawing PDFs.
      • PlanGrid: plangrid
      • Autodesk BIM 360 and A360 Drive: autodesk
      • Bluebeam Studio Prime: bluebeam
  • CRM Services

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

    • Google Calendar: google_calendar
    • Outlook Calendar: outlook_calendar
    • CalDAV: caldav
    • Exchange Server 2013+: exchange
    • iCloud Calendar: icloud_calendar
  • Email Services

    • Gmail: gmail
    • Microsoft Outlook Mail: outlook_email
      • Both consumer Outlook as well as Office 365
    • Microsoft Exchange Server 2007+: exchange_email
      • Features vary by Exchange Server version
    • IMAP/SMTP: imap (Alpha release)
  • Chat Services

    • Slack and Slack Enterprise Grid: slack
    • Microsoft Teams: ms_teams
  • 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.

Raw response headers are returned as a JSON encoded dictionary in the X-Kloudless-Raw-Headers header when X-Kloudless-Raw-Data: true is set. The services currently supported include:

  • salesforce

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:

  • autodesk

  • bluebeam

  • box

  • dynamics

  • egnyte

  • gdrive

  • gmail

  • google_calendar

  • hubspot

  • jive

  • kapost

  • onedrivebiz

  • oracle

  • outlook_calendar

  • plangrid

  • procore

  • salesforce

  • sharefile

  • sharepoint

  • skydrive

  • slack

  • sugarsync

  • zendesk

  • zoho

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

  • autodesk

  • bluebeam

  • box

  • caldav

  • dropbox

  • dynamics

  • egnyte

  • gdrive

  • gmail

  • google_calendar

  • hubspot

  • icloud_calendar

  • kapost

  • onedrivebiz

  • outlook_calendar

  • pipeliner

  • plangrid

  • powershell

    • See note under sharepoint for information on PowerShell queries
  • procore

  • salesforce

    • Most endpoints begin with /services/data/vXX.X/ where vXX.X is the API version such as v48.0. Make a pass-through request to /services/data first to determine available versions. Alternatively, request the user for this information as described in this Salesforce article.
  • servicenow

  • sharefile

  • sharepoint

  • skydrive

  • slack

  • sugarcrm

  • zendesk

  • zoho

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

curl -XPOST -H '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 encoded by Kloudless prior to being provided via the API. This encoding ensures that IDs can always be treated as arbitrary strings.

To refer to an object via the Kloudless API, first convert that object’s identifying information, such as its ID, to a Kloudless ID using this API endpoint. This allows you to use the encoded ID in API requests since Kloudless is able to decode it appropriately.

There are two ways to obtain the Kloudless ID for an object:

  1. Use the object’s raw ID returned by Kloudless. This already has all the object’s identifying information embedded within it.

  2. Create the ID from scratch by providing all the necessary identifying information to Kloudless.

Using the Kloudless-provided raw ID

The Kloudless API can return raw decoded IDs from upstream services.

For example, when requesting raw data with the X-Kloudless-Raw-Data: true header, Kloudless includes the fully assembled raw ID that it encodes into a Kloudless ID in the raw -> id attribute. This can be easily converted back into a Kloudless ID by providing it in the raw_id attribute in an API request to this endpoint as shown here:

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

The id attribute in the returned object can be used with the Kloudless API. The api and type attributes can be ignored.

This approach is most valuable when objects identified via raw data in Kloudless API responses need to be used with other Kloudless API endpoints.

Using raw data to create a Kloudless ID

The Kloudless API also supports receiving sufficient identifying information to encode the ID into the same format used by Kloudless.

For most services, the decoded ID is simply 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. For example, the id for the root folder in a Box account is 0, which is its ID in the Box API.

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 include file, folder, user, group, or any other object type documented or returned by Kloudless. object can be used to refer to any object if the type is unknown or unavailable. 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 -> id for the ID.

Here is an example request:

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 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.
    • team_drives: The “Shared Drives” folder with shared drives.
    • trash: The Trash folder.
  • s3, s3_compatible:

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

    • bucket_name: 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: The format of id for Message and Conversation objects:

    • For message objects, the id should be the Unix timestamp of the Message instead of the Slack Message ID, provided as a string.
    • When accessing conversation objects with an admin account (which uses the Discovery API), IDs should be the composition of the team ID and the conversation ID (channel, or gorup/private DM ID) in the format team:<team ID>:<conversation ID>.
  • 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.

  • outlook_calendar: See sharepoint for users and groups.

  • outlook_email: See sharepoint for users and groups.

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 is immediately returned with the 202 ACCEPTED status code and a Task object in the response body. The Task object’s ID can be used to retrieve the status of the API request as well as the result.

The following endpoints currently support asynchronous requests:

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

A request to this API endpoint returns either the Task object, for in-progress or unknown requests, or the final result or error for completed or failed Tasks respectively.

Once the Task has completed, the result is stored for up to 10 minutes, at which point the state expires and further queries indicate the Task is UNKNOWN instead.

The Task object returned has the following attributes:

  • id: Identifier used to reference the Task.

  • status: Current status of the request. One of:

    • UNKNOWN: The Task status is unknown. Our queue is either backed up, and we haven’t processed the Task yet, or the Task completed long enough ago that we no longer have its state cached.
    • STARTED: The Task was started and is currently in progress. Check back later to retrieve the result.
  • info: An optional JSON object some Tasks use to indicate their progress. null if unavailable. Comprised of:

    • time_elapsed: The time in seconds since Kloudless worker processes began processing the task.
    • time_remaining: The estimated remaining time in seconds until completion. null if unknown.
    • percent_completed: The estimated percentage of the task that is complete. For example, this is the percentage of a file that has been uploaded so far, for asynchronous file uploads. Here is a complete example:
    {
        "time_remaining": 484,
        "time_elapsed": 1466,
        "percent_completed": 75
    }

    This is currently only available for URL-based file uploads.

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

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.
entity_too_large 413 The request is larger than the server is willing or able to process.
locked 423 The resource attempting to be accessed is locked in the upstream service.
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.

Here are community-contributed projects:

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.


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.