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
  • Kapost: kapost
  • Asset Bank: asset_bank

• 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
    • Slack Files: slack
      • Refer to our connector guide for supported features.
    • Microsoft Teams Files: ms_teams
      • Refer to our connector guide for supported features.
  • 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:

• meta The Kloudless API itself. Refer to the Meta API for a list of object types.

• storage The Storage API.

• crm The CRM API.

• calendar The Calendar API.

• itsm The ITSM API.

• messaging The Chat API.

• email The Email API.

• activity The Activity Monitoring.

• team The Team API.

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 

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'

Raw Data -> Kloudless ID 

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

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

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

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:

• URL based file uploads

• Cross-account folder copies

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

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 the upstream service potentially rate limiting requests, 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 

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

SDKs 

We have currently created open source SDKs for the following languages:

• JavaScript

• Python

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

Here are community-contributed projects:

• Kloudless Ruby SDK

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.