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.
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
- Dropbox:
object_store
service group:- Amazon S3:
s3
- Azure Storage:
azure
- Amazon S3:
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 beFalse
. -
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 benull
for some services).total
space in bytes that that account can use in total (can benull
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 theaccount_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
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of account objects
- Parameters
- active
boolean
(optional)Retrieves only active/inactive accounts, if present.
Choices:
True
False
- page_size
number
(optional) Default: 10Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.- admin
boolean
(optional)Retrieves only admin/non-admin accounts, if present.
Choices:
True
False
- ordering
string
(optional) Default: -modifiedComing Soon
- search
string
(optional)Coming Soon
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 2, "count": 2, "page": 1, "objects": [ { "id": 90817234, "account": "someone@gmail.com", "service": "box", "service_name": "Box", "admin": false, "active": true, "created": "2015-03-17T20:42:17.954885Z", "modified": "2015-03-17T20:42:17.954885Z", "user_id": "uX1jd9af", }, { "id": 6535892, "account": "someone-else@gmail.com", "service": "egnyte", "service_name": "Egnyte", "admin": false, "active": true, "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "user_id": null, } ] }
Import an Account
Account creation is usually handled via Kloudless Authentication. However, this account creation endpoint can be used to import account and token information into Kloudless. This is useful when migrating existing cloud storage API tokens into Kloudless.
Here are the required parameters:
-
account
Described above. -
service
Described above. -
token
The token used to authenticate requests to the cloud storage service. e.g.: For services accessed via OAuth, this is the access token.
In addition, the following optional parameters may be provided:
-
token_secret
The OAuth token secret. -
refresh_token
The OAuth 2.0 refresh token. -
token_expiry
Described above. -
refresh_token_expiry
Described above.
Certain services require a few additional parameters as mentioned below.
-
sharefile
domain
The user’s ShareFile domain. This can be obtained from the response to a request for an access token.
-
egnyte
domain
The user’s Egnyte domain. This can be obtained from the URL users use to access their Egnyte account: https://domain.egnyte.com
-
sharepoint
,onedrivebiz
domain
The URL of the user’s SharePoint site. For example, https://contoso.sharepoint.com/sub-site, or for OneDrive for Business, https://contoso-my.sharepoint.com/personal/user_contoso_onmicrosoft_com
-
smb
domain
The host (and port if non-default) of the SMB server. For example,smb.company.com:1399
-
cmis
,alfresco
,alfresco_cloud
repository_url
The service URL of the CMIS repository. e.g. http://cmis.alfresco.com/cmisatom
-
webdav
protocol
: The WebDAV URL protocol. e.g.http
host
: The WebDAV host URL. e.g.host.example.com
port
: The WebDAV port. e.g.80
path
: The WebDAV path. e.g.webdav
-
cq5
protocol
: The Adobe CQ5 URL protocol. e.g.http
host
: The Adobe CQ5 host URL. e.g.host.example.com
port
: The Adobe CQ5 port. e.g.80
path
: The Adobe CQ5 path, which contains the following joined by a forward slash/
:- crx-path e.g.
crx
- repository e.g.
repository
- workspace e.g.
crx.default
- The example
path
would then becrx/repository/crx.default
- crx-path e.g.
- For more information, please visit: https://docs.adobe.com/docs/en/crx/2-3/how_to/webdav_access.html
-
hubspot
hub_id
The user’s Hub ID. It can be found at http://help.hubspot.com/articles/KCS_Article/Account/Where-can-I-find-my-HUB-ID
-
jive
community
The user’s Jive Community URL. It can be found after logging in here https://community.jivesoftware.com/login.jspa
-
salesforce
instance_url
Identifies the Salesforce instance to which API calls should be sent. e.g.https://na1.salesforce.com
identity_url
Identity URL that can be used to both identify the user as well as query for more information about the user. e.g.https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P
-
dynamics
resource
The URL of the user’s Dynamics CRM portal. e.g.https://mydomain.crm.dynamics.com
-
oracle
server_url
The Oracle Sales Cloud Host Server URL. e.g.https://123.crm.oraclecloud.com
-
google_calendar
monitor_calendars
Additional calendars to monitor events for. e.g.coworker@kloudless.com
Since token information is being imported, the credentials used to authenticate the user and obtain those tokens must be entered into the Kloudless Developer Portal. Otherwise, Kloudless will not be able to use the tokens to perform requests.
Please contact us for more information on how to migrate your app to our service with close to no downtime.
Example request:
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/'
- RequestToggle
Headers
Authorization: APIKey [KEY]
Content-Type: application/jsonBody
{ "account": "someone@gmail.com", "service": "copy", "token": "foo", "token_secret": "bar" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": 92386572, "account": "someone@gmail.com", "service": "copy", "service_name": "Copy", "admin": false, "active": true, "created": "2015-05-15T20:00:00Z", "modified": "2015-05-15T20:00:00Z", "token_expiry": null, "refresh_token_expiry": null, "user_id": null, }
Retrieve an Account
- Parameters
- active
boolean
(optional)Retrieves only an active/inactive account, if present.
Choices:
True
False
- retrieve_tokens
boolean
(optional) Default: FalseRetrieves
token
,token_secret
,token_expiry
,refresh_token_expiry
andaccount_id
for an account. Refer to the description of attributes above for more information. Please contact support@kloudless.com to enable access.Choices:
True
False
- retrieve_full
boolean
(optional) Default: TrueQueries the service for additional information and includes it in the metadata for the account. At the current time, this option populates the
quota
field. This parameter can be set toFalse
for efficiency reasons if only the other account metadata is required.Choices:
True
False
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 90817234, "account": "someone@gmail.com", "service": "box", "service_name": "Box", "admin": false, "active": true, "created": "2015-03-17T20:42:17.954885Z", "modified": "2015-03-17T20:42:17.954885Z", "token": "ABC123", "token_secret": "", "refresh_token": "XYZ456", "token_expiry": "2015-04-17T20:42:17.954885Z", "refresh_token_expiry": null, "account_id": "abc123xyz456", "user_id": "uX1jd9af", "quota": { "used": 316317438, "total": 2627241831 } }
Update an Account
When importing account/token information, you may wish to update Kloudless’ knowledge of tokens if you refresh them or obtain new tokens for the account. This endpoint will allow you to update the account with new information.
Here are the properties that can be updated:
-
active
-
account
-
service
-
token
-
token_secret
-
refresh_token
-
token_expiry
-
refresh_token_expiry
The new object will be returned on success.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"active": false}' \
'https://api.kloudless.com/v0/accounts/15'
Note that setting an account to inactive will cease attempts to refresh the
account’s refresh_token
causing the token to expire after the
refresh_token_expiry
if present. The user would then have to
reconnect their account to reactivate it.
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "active": false, }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 90817234, "account": "someone@gmail.com", "service": "box", "service_name": "Box", "admin": false, "active": false, "created": "2015-03-17T20:42:17.954885Z", "modified": "2015-05-15T06:12:00Z", "user_id": "uX1jd9af", }
Delete an Account
Example request:
curl -L -H 'Authorization: APIKey [KEY]' \
-XDELETE https://api.kloudless.com/v0/accounts/34
- Response
204
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
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of objects
The keys are sorted in descending order by modified
time.
Example request:
curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
'https://api.kloudless.com/v0/accounts/15/keys'
Note that since the keys
endpoint is nested under an account, it is also
possible to use the account key for that account itself to make this request:
curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
'https://api.kloudless.com/v0/accounts/15/keys'
This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be retrieved by separating the account IDs with commas:
curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
'https://api.kloudless.com/v0/accounts/15,16,17/keys'
- Parameters
- page_size
number
(optional) Default: 30Number of objects on each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 1, "count": 1, "page": 1, "objects": [ { "id": 20, "key": "KEI0SUlDSHrBVE1ulVGdmFsRJ", "active": true, "account": 15, "expiration": null, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-12T08:47:59.531726Z", } ] }
Retrieve an Account Key
Example request:
curl -L -H 'Authorization: AccountKey KEI0SUlDSHrBVE1ulVGdmFsRJ' \
'https://api.kloudless.com/v0/accounts/15/keys/20'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 20, "key": "KEI0SUlDSHrBVE1ulVGdmFsRJ", "active": true, "account": 15, "expiration": null, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-12T08:47:59.531726Z", }
Delete an Account Key
Deleting an account key will completely remove it, and not permit any further API requests using that Account Key.
You must provide the ID of the Account Key to delete in the URL as shown below
(e.g. 20
). You can retrieve the ID of the Account Key for your account by
performing a request to the
List Account Keys endpoint.
Example request:
curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
-XDELETE 'https://api.kloudless.com/v0/accounts/15/keys/20'
- Response
204
Account Key -> OAuth Token
Account Keys have been deprecated in favor of OAuth 2.0 Bearer Tokens, as described in the Authentication docs’ migration section. You can use this endpoint to create/retrieve the OAuth 2.0 Bearer token for the account, if the account has an Account Key associated with it.
Once you’ve obtained the OAuth 2.0 Token, please use that for future API requests. Please delete your account’s existing Account Key using the delete endpoint. This ensures that an attacker is unable to obtain an OAuth Token in the future using the Account Key.
Here is an example:
# 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 theraw_id
attribute for more information. -
name
File name -
size
File size in bytes. May benull
if unknown. -
created
ISO 8601 timestamp indicating when the file was created. May benull
if unknown. -
modified
ISO 8601 timestamp indicating when the file was last modified. May benull
if unknown. -
type
Will befile
. -
account
The id of the account that the file is associated with. -
parent
An object with metadata on the parent folder. Includes the parent’sid
, andname
where possible. -
ancestors
An object listing all the ancestor folders going back to the root folder, with the most immediate ancestor listed first. May benull
if not available. -
path
A human-readable path to the file in the account. May benull
if unknown. -
mime_type
The content type of the file. -
downloadable
A boolean indicating whether the file can be downloaded. -
raw_id
The decryptedid
. 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’sid
where possible. If theid
differs from the one returned by the Team endpoint, both are valid for that user. May not be present if unavailable. -
creator
Similar toowner
, but for the user that originally created the file. May not be present if unavailable. -
last_modifier
Similar toowner
, but for the user that last modified the file. May not be present if unavailable.
Upload a File
You can only upload files to folders that have can_upload_files
set to
true
. This is true for almost all folders except certain restricted
folders such as the root folder in a service that does not permit
file uploads to the root directory.
See the Folder Resource for more information.
To upload a file, POST the binary contents of the file to this endpoint with the headers containing the name of the file as well as the ID of the folder to upload the file to.
Required Headers:
-
X-Kloudless-Metadata
: A JSON string, with the attributes:parent_id
: The ID of the folder to upload the file to.name
: The name of the file being uploaded.
-
Content-Length
: The length of the request body in bytes.
Here is an example, with the file name héllö.png
and folder ID fL2hp
:
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
NOTE: Even though Kloudless does not impose any limits on the size of binary uploads, the upstream services (like Dropbox) can impose their own limits. It is recommended that the multipart upload endpoint be used for files larger than 100MB for services where it is supported.
You can also upload files from a URL instead. To do this, send a normal POST request with a JSON string with the attributes:
-
parent_id
: The ID of the Folder to upload the file to. -
name
: The name of the file being uploaded. -
url
: A URL the file can be accessed at. The response to a request to the URL must provide the size of the data being accessed in theContent-Length
header.
Here is an example:
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'
NOTE: Uploads via the url
option can be any size and will automatically
perform a multipart upload if required and supported.
We automatically rename uploaded files in the event of name conflicts (unless
the overwrite
parameter is set to True
). The resulting file name and
metadata will be returned upon success. We also enforce restrictions on file
names based on the underlying service.
Deprecated version: Previously, this endpoint accepted a multipart POST request that included the file data as well as other parameters such as the file name and parent ID. This has been deprecated and will be removed in the next version. For reference, the previous upload format is available here.
- Parameters
- overwrite
boolean
(optional) Default: FalseSpecifies whether to overwrite existing files
Choices:
False
True
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/octet-stream
X-Kloudless-Metadata: {"name": "test.png", "parent_id": "fL2hp"}
Content-Length: [SIZE OF FILE]Body
[file contents]
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL3Rlc3QucG5n", "name": "test.png", "size": 353953, "type": "file", "created": "2015-01-22T08:15:30.424173Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "path": "/All Files/Test folder/test.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, }
Retrieve File metadata
This will retrieve the metadata associated with the file object.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL3Rlc3QucG5n", "name": "test.png", "size": 353953, "type": "file", "created": "2015-01-22T08:15:30.424173Z", "modified": "2015-03-17T20:42:18.627533Z", "account" : 123, "path": "/All Files/Test folder/test.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": [ { "name": "Test folder", "id": "fL2Hp" }, { "name": "All Files", "id": "FrZekE==" } ], "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, }
Rename/Move a File
This allows you to modify file objects, which allows one to rename the file, move it to another directory within the current account, or move it to another account. Note that moving the file to a new location will remove the file from its previous location.
The request body may include the following optional attributes:
-
parent_id
: The ID of the folder to move the file to. Include this only when moving a file to a different directory. -
name
: The new name of the file. Include this only if the file’s name is being changed. -
account
: The ID of the account to move the file to. Include this only when moving a file to an account different from the one the file currently resides in. Theparent_id
must also be specified. -
user
: The ID of the user whose folder the file is being moved to. Include this only if the destination account is an admin account and requires impersonation to transfer the file to the new location. User IDs may be obtained from the Team endpoint. Theparent_id
must also be specified. This field is required when impersonating users since theX-Kloudless-As-User
header only determines the user to impersonate when accessing the file at its current location, and not the user to impersonate when transferring the file to its new location. If the users are the same, this field may be omitted.
More than one action can be performed at once. For example, you can transfer the file to another account and give it a different name as is shown in the following example:
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=='
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "name": "new-cool-name.png", "parent_id": "fL2hp", "account": 124, }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL2hpL3Rlc3QucG5n", "name": "new-cool-name (2).png", "size": 353953, "type": "file", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 124, "path": "/All Files/Test folder/new-cool-name (2).png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr=" }, "mime_type": "image/png", "downloadable": true, }
Update File content
This will create a new version/overwrite the file and return the updated metadata for the file object on success.
NOTE: Even though Kloudless does not impose any limits on the size of binary uploads, the upstream services (like Dropbox) can impose their own limits. It is recommended that the multipart upload endpoint be used for files larger than 100MB for services where it is supported.
Here is an example command of updating the file contents:
curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
--data-binary @/path/to/local/file \
'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Length: [SIZE OF FILE]Body
[file data binary]
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL2hpL3Rlc3QucG5n", "name": "new-cool-name (2).png", "size": 353953, "type": "file", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-05-20T08:00:00Z", "account": 124, "path": "/All Files/Test folder/new-cool-name (2).png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr=" }, "mime_type": "image/png", "downloadable": true, }
Download a File
This is a direct download of the file. We proxy the download directly from the cloud storage service so we never store your users’ files.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnXJwCg==/contents'
- Parameters
- content_type
string
(optional)If the file can be downloaded in multiple formats, this recommends a content type to use. For example,
application/pdf
to download a file as a PDF. If the requested format is unavailable, this field will be ignored and the file will be downloaded as usual. Currently supported for:- Google Documents
(
gdrive
) Google Documents will automatically be downloaded in the corresponding Office format, but you may also specify an alternate format using this parameter.
- Google Documents
(
Download a Thumbnail for a File
/accounts/{account_id}/files/{file_id}/thumbnail{?size, image_format}
Thumbnails can be downloaded for files where available from the third-party service. Downloading a thumbnail is handled similar to file downloads with the data streamed through Kloudless in memory.
This feature is currently available for the following services and formats:
-
box
:png
,jpeg
-
gdrive
:jpeg
-
dropbox
:png
,jpeg
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnXJwCg/thumbnail/?size=400'
- Parameters
- size
integer
(optional) Default: 256 preferredSpecifies a target size for which a thumbnail of equivalent size or larger, if possible, will be downloaded. Defaults to 256, or the default format of the third-party service if 256 is not supported.
Choices:
[1..1024]
- image_format
string
(optional) Default: 'png' preferredSpecifies the requested format of the thumbnail. Defaults to ‘png’, or the default format of the third-party service if ‘png’ is not supported. The ‘Content-Type’ header in the response will contain the type of the thumbnail data returned.
Copy a File
To make a copy of the file you can specify the following fields in a JSON object to describe the operation that will be performed:
The request body may include the following attributes:
-
parent_id
(required): The ID of the folder to copy the file to. -
name
(optional): The new name of the file. Include this only if the file’s name is being changed. -
account
(optional): The ID of the account to copy the file to. Include this only when moving a file to an account different from the one the file currently resides in. -
user
(optional): The ID of the user whose folder the file is being moved to. Include this only if the destination account is an admin account and requires impersonation to copy the file to the new location. User IDs may be obtained from the Team endpoint. This field is required when impersonating users since theX-Kloudless-As-User
header only determines the user to impersonate when accessing the file at its current location, and not the user to impersonate when copying the file to its new location. If the users are the same, this field may be omitted.
Example request:
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'
If you wish to move the file rather than copy it, update its metadata instead.
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "name": "copied-file.png", "parent_id": "fL2hp", }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL2hpL3Rlc3QucG5n", "name": "copied-file.png", "size": 353953, "type": "file", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 124, "path": "/All Files/Test folder/copied-file.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "qtk9cJKaprqHQf399JXB1NAzckii0G4ZeTemchFWKWr=" }, "mime_type": "image/png", "downloadable": true, }
Delete a File
Files may be permanently deleted, bypassing any Trash folder if present,
by setting permanent
to True
. This feature can be used for the following services:
-
box
-
gdrive
-
sharepoint
-
onedrivebiz
-
sharefile
Some services may still provide a mechanism for users to restore the file.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' -XDELETE \
'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg=='
- Parameters
- permanent
boolean
(optional) Default: FalseIf
False
, files will be sent to the service’s Trash folder or equivalent if available. If no Trash is present, the file will be permanently deleted. IfTrue
, behaves similarly to no Trash being present and deletes the file.Choices:
True
False
- Response
204
Create an Upload URL for a File
/accounts/{account_id}/files/upload_url{?overwrite,expires_in,use_http}
To upload a file via the Kloudless API, please use the upload endpoint instead.
In some cases, it is preferable to have the client directly upload a file to a third-party storage service. While this is usually unnecessary, this endpoint may be used if required. Kloudless can generate a signed URL to provide to a client to upload the data to.
To create the URL, perform a POST request with a JSON object with the following attributes:
-
parent_id
: The ID of the Folder to upload the file to. -
name
: The name of the file being uploaded.
Here is an example:
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"}' \
The response contains the URL and the HTTP method to use to upload the binary content of the file.
This endpoint is currently available for the following services:
s3
- Parameters
- overwrite
boolean
(optional) Default: FalseSpecifies whether to overwrite existing files
Choices:
False
True
- expires_in
integer
(optional) Default: 300Specifies the duration of availability of the upload url.
Choices:
[1..10000]
- use_http
boolean
(optional) Default: FalseSpecifies whether the upload url should use HTTP instead of HTTPS. If a service only supports one of the protocols, this parameter will be ignored and a url using that protocol will be returned.
Choices:
False
True
Raw ID -> Kloudless ID
/accounts/{account_id}/convert_id{?retrieve_metadata}
This endpoint converts IDs retrieved by connecting directly to a cloud service into a Kloudless ID usable with the Kloudless API. It is currently intended for use with file and folder IDs.
Kloudless also enables you to convert IDs in the other direction, from an
encoded Kloudless ID to a raw ID you can use directly with a cloud service.
See the raw_id
attribute for more information.
To retrieve the Kloudless ID, perform a POST with a JSON object with the following attributes:
-
raw_id
: Properly formatted raw resource ID. -
type
: The type of resource (e.g.file
,folder
, etc.).
Here is an example:
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"}'
The response contains a usable Kloudless ID and the resource’s metadata if requested. Fetching the metadata ensures that the ID passed in is valid and that the underlying resource exists. Since requesting the metadata requires performing a request to the underlying service, you can optimize performance by skipping validation and only retrieving the ID if that is all that is needed.
- Parameters
- retrieve_metadata
boolean
(optional) Default: FalseSpecifies whether to retrieve the resource’s metadata or not.
Choices:
False
True
List Recent Files
This retrieves a list of files in a user’s account, sorted in descending order by modified time.
This feature is available for a subset of services. The services supported are the same as those listed under the events endpoint.
To enable access to recent file activity for accounts connected to your application, visit the App Details page and ensure the checkbox for ‘Collect Recent File data’ is checked.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/recent'
This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be retrieved by separating the account IDs with commas:
curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
'https://api.kloudless.com/v0/accounts/123,456,789/recent'
- Parameters
- page_size
number
(optional) Default: 30Number of objects on each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.- after
ISO 8601 timestamp
(optional)Only files updated after this time will be returned.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 3, "count": 3, "page": 1, "files": [ { "id": "fL2hpL3Rlc3QucG5n", "name": "test-1.png", "size": 353953, "type": "file", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "path": "/All Files/Test folder/test-1.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, }, { "id": "fL2hpL3Rlc3QucG5o", "name": "test-2.png", "size": 353953, "type": "file", "created": "2015-03-16T20:42:18.627533Z", "modified": "2015-03-16T20:42:18.627533Z", "account": 123, "path": "/All Files/Test folder/test-2.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, }, { "id": "fL2hpL3Rlc3QucG5x", "name": "test-3.png", "size": 353953, "type": "file", "created": "2015-03-15T20:42:18.627533Z", "modified": "2015-03-15T20:42:18.627533Z", "account": 456, "path": "/All Files/test2/Test folder/test-3.png", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "jtadjYiSkjLbUJuIglJXRsfDF51RfQGQUNL4lekbIG3jl=" }, "mime_type": "image/png", "downloadable": true, } ] }
Search
This is a limited release of Search. Services currently supported are:
-
dropbox: file name
-
box: file name and contents
-
gdrive: file name and contents
-
skydrive: file name
-
evernote: file name
-
sharepoint: file name and contents
-
onedrivebiz: file name and contents
-
egnyte: file name and contents
-
sharefile: file name and contents
-
cmis: file name and contents
-
alfresco: file name and contents
-
alfresco_cloud: file name and contents
-
salesforce: any text-based field
-
hubspot: file name
-
jive: file name
with more in the works!
The response contains the following information:
-
count
Number of file objects in search results. -
objects
List of file objects in search results, in decreasing order of relevancy. -
errors
Contains account IDs mapped to error responses for any accounts that failed the API request. Only present when performing multi-account searches (see below).
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/search?q=hello+world'
This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be searched by separating the account IDs with commas:
curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
'https://api.kloudless.com/v0/accounts/123,456,789/search?q=hello+world'
Search result ordering is determined by the underlying cloud storage service’s search API where possible, or by our search cluster if needed. The search results are evenly interleaved when multiple accounts are searched simultaneously. For example, in the cURL request above, the results would be in the order: Acct. ‘123’ Result #1, 456 #1, 789 #1, 123 #2, 456 #2, 789 #2, etc.
- Parameters
- q
string
(required)The terms to search for.
- page_size
number
(optional) Default: 30Coming Soon. Number of objects on each page. The
page_size
must be between1
and100
.- page
number
(optional) Default: 1Coming Soon. Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 2, "objects": [ { "id": "fxZn2Gnd9v", "name": "hello.png", "size": null, "type": "file", "created": "2015-03-17T20:00:00Z", "modified": "2015-03-17T20:00:00", "account": 123, "path": null, "parent": { "id": "root", "name": "Google Drive" }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, }, { "id": "fL3Rlc3QucG5n", "name": "Around the World in Eight Days.pdf", "size": 353953, "type": "file", "created": "2015-01-22T08:15:30.424173Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "path": null, "parent": { "id": "fN2BVsAty3v2b", "name": "Classics" }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "application/pdf", "downloadable": true, } ] }
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:
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
To begin a multipart session, POST a JSON object with the information below:
-
name
: The name of the file to upload. -
parent_id
: The ID of the parent folder to upload the file to. -
size
: The total size of the file being uploaded. The services below require this information and will error if not provided:autodesk
gdrive
egnyte
skydrive
Multipart Uploads to other services do not require this field.
The response will contain the following information:
-
id
: The ID of the new multipart resource you will be interacting with. Use this ID to reference the session and upload parts. -
account
: The ID of the account that the multipart resource is associated with. -
part_size
: Each part but the last must be this size in bytes in order for the upload to succeed. -
parallel_uploads
: A boolean value that determines whether the chunks can be uploaded in parallel. Iffalse
, they must be uploaded serially, in order.
Example request:
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'
- Parameters
- overwrite
boolean
(optional) Default: FalseIf
True
, an existing file with the same name will be overwritten by the uploaded file. IfFalse
, an alternate name will be chosen for the file.Choices:
True
False
Retrieve Multipart Session Information
This endpoint is used to query information about an existing multipart session. The following information is returned:
-
id
: The ID of the new multipart resource you will be interacting with. -
account
: The ID of the account that the multipart resource is associated with. -
part_size
: Each part but the last must be this size in bytes in order for the upload to succeed. -
parallel_uploads
: A boolean value that determines whether the chunks can be uploaded in parallel. Iffalse
, they must be uploaded serially, in order.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 543, "account": 123, "part_size": 5242880, "parallel_uploads": true, }
Upload Part
Parts of a file can be uploaded in any order as long as the part_number
corresponds to the order in which the part appears in the original file.
IMPORTANT: All of the parts but the last must be equal to the part size that gets returned when the multipart session gets created. If the file that you are uploading is smaller than that, you should use the normal upload endpoint for files.
Example request:
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'
- Parameters
- part_number
integer
(required) Example: 1The index of the part.
Choices:
[1..10000]
- RequestToggle
Headers
Content-Type: application/octet-stream
Body
[binary contents of file part]
- Response
200
Finalize Multipart Session
Once all of the parts are uploaded, the session must be finalized to create the new file. This will combine all of the parts and return the metadata for the new file.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
-XPOST 'https://api.kloudless.com/v0/accounts/123/multipart/543/complete'
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL3Rlc3QtYmlnLWZpbGUuaXNvCg==", "name": "test-big-file.iso", "size": 157286400, "type": "file", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "path": "/Test folder/test-big-file.iso", "parent": { "id": "fL2Hp", "name": "Test folder", }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "application/octet-stream", "downloadable": true, }
Abort Multipart Session
This will abort the upload session and remove all uploaded parts from the upstream cloud storage service. This must be done if you do not want to resume a multipart upload session and do not want to incur additional storage charges from the upstream service.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
-XDELETE 'https://api.kloudless.com/v0/accounts/123/multipart/543'
- Response
204
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
anddownloadable
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
When creating folders, we do not rename them if a folder of the same name exists; we simply return the ID of the existing folder with that name. This behavior will be configurable soon.
Some services contain special folders in which you cannot create new folders,
and we will return an error if you attempt to do so. These folders will
have can_create_folders
set to false
in their metadata.
Example request:
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'
- Parameters
- conflict_if_exists
boolean
(optional) Default: FalseIf
False
, this will search for and return an existing folder with the samename
if present, rather than attempting to create the folder. IfTrue
, this may result in an error with status code 409 if the location already contains a folder with the same name.Choices:
True
False
- RequestToggle
Headers
Content-Type: application/json
Body
{ "parent_id": "root", "name": "New folder inside root directory" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "fTmV3IEZvbGRlcg==", "name": "New Folder inside root directory", "size": 5135, "type": "folder", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": "123", "can_create_folders": true, "can_upload_files": true, "path": null, "parent": { "id": "root", "name": "Google Drive", }, "ancestors": null, }
Retrieve Folder Metadata
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "fTmV3IEZvbGRlcg==", "name": "New Folder", "size": 5135, "type": "folder", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": "123", "can_create_folders": true, "can_upload_files": true, "path": null, "parent": { "id": "root", "name": "Google Drive", }, "ancestors": null, }
Retrieve Folder Contents
/accounts/{account_id}/folders/{folder_id}/contents{?page_number,page_size,recursive,ordering}
The folder_id root
can be used to list the contents of the root folder.
The response contains the following information:
-
count
: Integer. Number of child files/folders in this folder. -
objects
: Array. List of file/folder metadata objects. -
page
Integer/String. Identifier of the returned page. -
next_page
Integer/String. Identifier of the next page.null
if no further pages available. -
has_next
Boolean. (Deprecated: seenext_page
instead) Whether there is a next page.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/contents'
The folder_id trash
can be used to list the Trash or Recycle Bin for the
following services:
-
box
-
gdrive
-
sharepoint
-
onedrivebiz
- Parameters
- page
integer
(optional) Default: 1The number of the page you wish to fetch. Must be greater than 0.
- page_size
integer
(optional) Default: 1000The number of elements per page that should be returned. Must be greater than or equal to 100 and less than or equal to 1000. Page sizes are treated as advisory. If a
page_size
is outside the range supported by a service, the closest supported value will be used.- recursive
boolean
(optional) Default: FalseAll files and folders within this folder will be returned if possible. Only folders with
can_list_recursively
set totrue
can have their contents listed recursively. Currently supported for:-
dropbox
-
gdrive
Only for the root folder. -
sharepoint
Only for the root folder of a document library. -
onedrivebiz
Only fo the root folder of a document library.
-
- ordering
string
(optional) Default: nameOrder the list of children. Ascending order is specified by default and descending order is specified by prefixing field with
-
(e.g.ordering=name
results in A-Z ordering,ordering=-name
results in Z-A ordering). Multiple sorting fields can be used where supported (e.g.ordering=name,-size
).The possible fields to order by are:
-
name
-
created
-
modified
-
creator
-
size
-
last_modifier
This capability is only supported by the following services:
-
sharepoint
Document Libraries only; single sort field. -
onedrivebiz
Document Libraries only; single sort field.
-
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 2, "page": 1, "next_page": null, "objects": [ { "id": "fyGb2xkZXIgTmFtZQ==", "name": "Child Folder", "size": null, "type": "folder", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "can_create_folders": true, "can_upload_files": true, "path": null, "parent": { "id": "root", "name": "Google Drive", }, "ancestors": null, }, { "id": "fL3Rlc3QucG5n", "name": "test.png", "size": 353953, "type": "file", "created": "2015-01-22T08:15:30.424173Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 123, "path": null, "parent": { "id": "root", "name": "Google Drive", }, "ancestors": null, "owner": { "id": "ua2xvdWRmJ7XFSHh4u2Bnwm9a38RoeUBnbWFpbC5jb20=" }, "mime_type": "image/png", "downloadable": true, } ] }
Rename/Move a Folder
Renaming or moving folders can be done similarly to moving files.
As mentioned in the docs for renaming/moving files,
the name
and/or parent_id
of the new folder may be specified.
We currently do not support moving entire folders between
cloud storage accounts. However, the user
attribute is supported for moving
folders between users within the same admin account.
See the Files endpoint for more information.
Here is an example:
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=='
The metadata of the new folder is returned.
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "parent_id": "faGVycGFkZXJwZGlyCg==", "name": "New Folder Name" }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL2hpL05ldyBGb2xkZXIgTmFtZQ==", "name": "New Folder Name", "size": 5135, "type": "folder", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": "123", "can_create_folders": true, "can_upload_files": true, "path": "/All Files/New folder/New Folder Name", "parent": { "id": "faGVycGFkZXJwZGlyCg==", "name": "New Folder", }, "ancestors": null, }
Copy a Folder
This endpoint is supported by the services mentioned below.
Some services require custom OAuth credentials, configurable through the developer portal, to prevent rate limiting:
-
gdrive
-
skydrive
-
sugarsync
-
s3
-
salesforce
-
hubspot
NOTE: Response times for the above services scale with the size of the folder being copied, and currently do not succeed if the copy operation takes longer than 15 minutes to process. This is because Kloudless individually copies each file in the folder.
The following services are also supported, but do not require custom OAuth credentials as they natively support folders being copied:
-
dropbox
-
box
-
sharefile
-
evernote
-
sharepoint
-
onedrivebiz
To make a copy of the folder, you may specify the parent_id
, name
and
user
fields in a JSON object in a manner similar to the mechanism
used for copying files.
We do not currently support using the account
attribute to copy folders
between different accounts.
Using the user
attribute to copy folders between users within an admin
account is supported for the services listed above that natively support
folders being copied (e.g. box
, sharepoint
, etc.).
Example request:
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'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "name": "Copied Folder", "parent_id": "fL2hp", }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "fL2hpL3Rlc3QucG5n", "name": "Copied Folder", "size": 353953, "type": "folder", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z", "account": 12, "can_create_folders": true, "can_upload_files": true, "path": "/All Files/New Folder/Copied Folder", "parent": { "id": "fL2hp", "name": "New Folder", }, "ancestors": null, }
Delete a Folder
Deleting a folder can be done recursively by setting the recursive
parameter
to True
. To delete the folder only if the folder is empty, set the
recursive
parameter to False
.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' -XDELETE \
'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg=='
- Parameters
- recursive
boolean
(optional) Default: FalseIf
True
, folders will be deleted even if they are not empty.Choices:
True
False
- permanent
boolean
(optional) Default: FalseIf
False
, folders will be sent to the service’s Trash folder or equivalent if available. If no Trash is present, the folder will be deleted. IfTrue
, behaves similarly to no Trash being present and deletes the folder.Choices:
True
False
- Response
204
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 toreader
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
Retrieves all permission information associated with a file or folder ID.
The response contains the following information:
permissions
A list of permission objects belonging to this resource. Each object contains information as described in Permissions above.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/folders/fTmV3IEZvbGRlcg==/permissions'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "permissions": [ { "id": "uGWK298eguSG2==", "email": "writer@test.com", "name": "Test Writer", "role": "writer", "type": "user" }, { "id": "ucvOO2ZWsCtpVLcqt4CDC1A", "email": "user@test.com", "name": "Test User", "role": "owner", "type": "user" }, { "id": "gNTQ==", "name": "Test Group", "role": "writer", "type": "group" } ] }
Set Permissions
To set permissions on a resource, provide a list of permission objects representing all permission data for the resource. Any existing permissions on the resource will be overwritten.
If you would prefer to only alter a subset of permissions, use the PATCH endpoint instead.
Each permission object should include the following attributes:
-
type
Specifies the type of assignee. Should be eitheruser
orgroup
unless Kloudless provides other types of permission objects for a resource. -
role
The assignee’s role, as described above in Permissions. -
id
ID of the user, group or permission object. -
email
Can be optionally used to identify the user instead of theid
.
Here is an example:
[
{
"type": "user",
"email": "reader@test.com",
"role": "reader"
},
{
"type": "user",
"id": "uGWK298eguSG2==",
"role": "writer"
}
]
Above, access to the file will be added/updated for the two users and access for any other existing users/groups will be removed.
The response contains a list of permission objects for the resource, similar to that obtained by the list endpoint.
Example request:
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'
Deprecated version: Previously, this endpoint allowed user permissions to be modified by accepting a mapping of emails to roles. This has been deprecated and will be removed in the next version. For reference, the previous request format is available here.
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
[ { "type": "user", "id": "uGWK298eguSG2==", "role": "writer" } ]
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "permissions": [ { "id": "uGWK298eguSG2==", "email": "writer@test.com", "name": "Test Writer", "role": "writer", "type": "user" } ] }
Update Permissions
Individual permissions can be added, updated or removed with this endpoint. See the PUT endpoint for more information on the request format to add or update permission data.
To remove access to a resource, include the relevant permission object similar
to an add/update but set the role to an empty string: ""
.
This will remove any permissions belonging to the identified assignee.
Here is an example permission list:
[
{
"type": "user",
"email": "reader@test.com",
"role": "reader"
},
{
"type": "user",
"id": "uGWK298eguSG2==",
"role": "writer"
},
{
"type": "group",
"id": "gNTQ==",
"role": ""
}
]
Above, access to the file will be added/updated for the two users and access will be revoked for the group.
The response contains a list of permission objects for the resource, similar to that obtained by the list endpoint.
Example request:
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'
Deprecated version: Previously, this endpoint allowed user permissions to be modified by accepting a mapping of emails to roles. This has been deprecated and will be removed in the next version. For reference, the previous request format is available here.
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
[ { "type": "user", "id": "uEZEKdS4Webxw==", "role": "writer" }, { "type": "group", "id": "gNTQ==", "role": "" } ]
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "permissions": [ { "id": "uEZEKdS4Webxw==", "email": "user10@test.com", "name": "Test promoted reader", "role": "writer", "type": "user" }, { "id": "utgn5eQDvwp6pD3wBGli3Q==", "email": "previewer@test.com", "name": "Test Previewer", "role": "previewer", "type": "user" } ] }
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
Retrieves all properties for a given file.
The response contains the following information:
properties
A list of user-defined properties belonging to this file. Each object contains information as described in Properties above.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/files/fTmV3IEZvbGRlcg==/properties'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "properties": [ { "key": "department", "value": "engineering", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z" }, { "key": "readonly", "value": "true", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-03-17T20:42:18.627533Z" } ] }
Update Properties
Update, add, or delete one or more properties for a given file.
The request body should be a list of objects consisting of key-value pairs.
Specifying a property with the value null
will delete that property.
Example request body:
[
{
"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"
}
]
NOTE: For Box files, you can additionally specify a box_scope
and box_template
with each key-value pair. These two fields default to global
and properties
, respectively.
The response contains the following information:
properties
A list of user-defined properties belonging to this file. Each object contains information as described in Properties above.
Example request (using the above request body):
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'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "properties": [ { "key": "department", "value": "marketing", "created": "2015-03-17T20:42:18.627533Z", "modified": "2015-07-16T22:49:55.984Z" }, { "key": "category", "value": "sales", "created": "2015-07-16T22:49:55.984Z", "modified": "2015-07-16T22:49:55.984Z" } ] }
Delete all Properties
Deletes all properties for a given file.
Example request:
curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/files/fTmV3IEZvbGRlcg==/properties'
- Response
204
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 querystringinline=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
Iftrue
, resolves directly to the contents of the file and downloads it. Iffalse
, 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
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of link objects
The links are sorted in descending order by modified
time.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/15/links'
This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be retrieved by separating the account IDs with commas:
curl -L -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
'https://api.kloudless.com/v0/accounts/15,16,17/links'
- Parameters
- active
boolean
(optional)Retrieves only active/inactive links, if present.
Choices:
True
False
- page_size
number
(optional) Default: 30Number of objects on each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 1, "count": 1, "page": 1, "objects": [ { "id": "aZ9APHB0OrTTP74ia9xc", "file_id": "fMEI0SUlDSHrBVE1uVWFrbXRabkZtVlVGdmFsRQ==", "file_name": "test.txt", "url": "https://kloudl.es/l/aZ9APHB0OrTTP74ia9xc", "account": 15, "active": true, "expiration": null, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-12T08:47:59.531726Z", "direct": false, } ] }
Create a Link
To create a new link, just post a JSON object with these attributes:
file_id
The ID of the file to link to.
In addition, the following optional attributes can be included:
-
password
Password for the link -
expiration
ISO 8601 timestamp specifying when the link expires. -
direct
Boolean specifying whether this link is a direct link or not. See Link attribute docs above for more information ondirect
.
Example request:
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'
To make a direct link:
curl -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
-d '{"file_id": "fMEI0H4PP5", "direct": true}' \
'https://api.kloudless.com/v0/accounts/15/links'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "file_id": "fMEI0H4PP5", "expiration": "2015-01-01T00:00:00", }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "aZ9APHB0OrTTP74ia9xc", "active": true, "file_id": "fMEI0H4PP5", "account": 15, "url": "https://kloudl.es/l/aZ9APHB0OrTTP74ia9xc", "expiration": "2015-01-01T00:00:00Z", "password": false, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-12T08:47:59.531726Z", "direct": false, }
Retrieve a Link
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/15/links/aZ9APHB0OrTTP74ia9xc'
- Parameters
- active
boolean
(optional)Retrieves only an active/inactive link, if present.
Choices:
True
False
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "aZ9APHB0OrTTP74ia9xc", "active": true, "file_id": "fMEI0H4PP5", "account": 15, "url": "https://kloudl.es/l/aZ9APHB0OrTTP74ia9xc", "expiration": null, "password": true, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-12T08:47:59.531726Z", "direct": false, }
Update a Link
When updating a link, you can update any of the following properties by supplying their new values in a JSON object:
-
active
-
expiration
-
password
The new object will be returned on success.
Example request:
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'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "active": false, }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "aZ9APHB0OrTTP74ia9xc", "active": false, "file_id": "fMEI0H4PP5", "account": 15, "url": "https://kloudl.es/l/aZ9APHB0OrTTP74ia9xc", "expiration": null, "password": true, "created": "2015-03-12T08:47:59.531726Z", "modified": "2015-03-17T21:30:18.728940Z", "direct": true, }
Delete a Link
Deleting a link will completely remove it (as opposed to disabling it by
setting active
to false
).
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
-XDELETE \
'https://api.kloudless.com/v0/accounts/15/links/aZ9APHB0OrTTP74ia9xc'
- Response
204
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): Theid
of the file that the event refers to -
event_id
: Theid
of the event that is created -
account
: Theid
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 usetype
. -
modified
: The time the event occurred. This is not always precise due to the underlying service. Will benull
if unavailable. -
type
: Any of the types described in Event types -
ip
: User’s IP Address, if available. May benull
. -
metadata
: The new metadata of the file ornull
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
Events are retrieved using this endpoint. They are returned as a list of event objects in the order that our system was made aware of them. There is a small chance that there will be duplicate events in the stream, but the net result of applying all of these events will reflect the current state of the underlying storage service.
The response contains the following fields:
-
objects
: List of the events that have taken place. -
cursor
: A number identifying a location in the stream immediately after the events described inobjects
. -
count
: Number of events returned. -
remaining
: Number of events remaining in the stream.
The returned cursor should be used in subsequent requests so that only events that have not been seen previously are returned.
Example Request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/events?cursor=121'
- Parameters
- cursor
string
(optional)The last cursor in the event stream that your application has seen. The cursor can also be set to
after-auth
, which will retrieve events that have occurred after the account was connected. This is useful if prior events are unnecessary.- page_size
number
(optional) Default: 1000Number of events in the stream to return, if available. The
page_size
must be greater than or equal to1
and less than or equal to1000
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "cursor": 330, "count": 3, "remaining": 0, "objects": [ { "metadata": { "size": 5422, "mime_type": "image/png", "downloadable": true, "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==", "type": "file", "account": 613076, "name": "logo_white_146x58.png", "parent": { "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==", "name": "Shared Documents" }, "ancestors": null, "owner": { "id": "n1nNjHU4FP37p2VEmtZqmLQFN4BydJwiPV5YdiSqO=" }, "created": null, "modified": "2015-10-02T21:38:03Z", "path": "/Shared Documents/logo_white_146x58.png" }, "action": "+", "account": 613076, "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==", "event_id": 320, "user_id": null, "type": "add", "previous_metadata": {}, }, { "metadata": { "size": 5391, "mime_type": "image/png", "downloadable": true, "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==", "type": "file", "account": 613076, "name": "test (2).png", "parent": { "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==", "name": "Shared Documents" }, "ancestors": null, "owner": { "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj=" }, "created": null, "modified": "2015-10-02T20:52:41Z", "path": "/Shared Documents/test (2).png" }, "action": "+", "account": 613076, "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==", "event_id": 326, "user_id": null, "type": "add", "previous_metadata": {}, }, { "metadata": { "size": 5391, "mime_type": "image/png", "downloadable": true, "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==", "type": "file", "account": 613076, "name": "test (2).png", "parent": { "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==", "name": "Shared Documents" }, "ancestors": null, "owner": { "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj=" }, "created": null, "modified": "2015-10-02T20:52:45Z", "path": "/Shared Documents/test (2).png" }, "action": "-", "account": 613076, "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==", "event_id": 330, "user_id": null, "type": "delete", "previous_metadata": {}, } ] }
Retrieve Latest Cursor
This returns the latest cursor that is available. This makes it easier to start fetching new events immediately, rather than making a potentially large initial request.
This returns a dictionary with a single field:
cursor
: The most recent cursor for this account
Example Request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/events/latest'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "cursor": 29 }
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
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
egnyte
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
count
Number of users on this page. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
objects
List of users. Each user object has:-
id
The ID of the user. Use this as the value of theX-Kloudless-As-User
header to perform API requests as this user. -
name
The name of the user. -
email
An email associated with the user. -
type
Always ‘user’.
-
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/users'
- Parameters
- page_size
number
(optional) Default: 1000Number of objects on each page. The
page_size
must be greater than or equal to100
and less than or equal to1000
. Page sizes are treated as advisory. If apage_size
is outside the range supported by a service, the closest supported value will be used.- page
string
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects. Each response will contain the next page’s identifier in thenext_page
attribute. That identifier must be provided here to retrieve the next page.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 1, "next_page": null, "page": "1", "objects": [ { "id": "u4806226", "name": "Test User", "email": "user@test.com", "type": "user", }, ], }
Retrieve a User
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
id
The ID of the user. Use this as the value of theX-Kloudless-As-User
header to perform API requests as this user. -
name
The name of the user. -
email
An email associated with the user. -
type
Always ‘user’.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/users/u4806226'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "u4806226", "name": "Test User", "email": "user@test.com", "type": "user", }
List a User's Group Memberships
/accounts/{account_id}/team/users/{user_id}/memberships{?page_size,page}
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
count
Number of objects on this page. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
objects
List of groups the user is in. Each group object has:-
id
The ID of the group. -
name
The name of the group. -
role
The role of the user in the group. May be one of the following:member
: The user is a member of the group.admin
: The user is an admin of the group.
-
type
Always ‘group’. -
email
An email associated with the group, if any. Not present if unavailable.
-
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/users/u4806226/memberships'
- Parameters
- page_size
number
(optional) Default: 1000Number of objects on each page. The
page_size
must be greater than or equal to100
and less than or equal to1000
.- page
string
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects. Each response will contain the next page’s identifier in thenext_page
attribute. That identifier must be provided here to retrieve the next page.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 1, "next_page": null, "page": "1", "objects": [ { "id": "g982734", "name": "Test Group", "role": "admin", "type": "group", }, ], }
List Groups
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
count
Number of objects on this page. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
objects
List of groups. Each group has:-
id
The ID of the group. -
name
The name of the group. -
type
Always ‘group’. -
email
An email associated with the group, if any. Not present if unavailable.
-
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/groups'
- Parameters
- page_size
number
(optional) Default: 1000Number of objects on each page. The
page_size
must be greater than or equal to100
and less than or equal to1000
. Page sizes are treated as advisory. If apage_size
is outside the range supported by a service, the closest supported value will be used.- page
string
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects. Each response will contain the next page’s identifier in thenext_page
attribute. That identifier must be provided here to retrieve the next page.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 1, "next_page": null, "page": "1", "objects": [ { "id": "g982734", "name": "Test Group", "type": "group", }, ], }
Retrieve a Group
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
id
The ID of the group. -
name
The name of the group. -
type
Always ‘group’. -
email
An email associated with the group, if any. Not present if unavailable.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/groups/g982734'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "g982734", "name": "Test Group", "type": "group", }
List a Group's Members
Services currently supported are:
-
dropbox
-
gdrive
-
box
-
sharepoint
-
onedrivebiz
The response contains the following information:
-
count
Number of objects on this page. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
objects
List of the group’s users. Each object has:-
id
The ID of the user. -
name
The name of the user. -
email
The email address of the user. -
role
The role of the user in the group. Seerole
in group memberships. -
type
Always ‘user’.
-
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/123/team/groups/g982734/members'
- Parameters
- page_size
number
(optional) Default: 1000Number of objects on each page. The
page_size
must be greater than or equal to100
and less than or equal to1000
. Page sizes are treated as advisory. If apage_size
is outside the range supported by a service, the closest supported value will be used.- page
string
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects. Each response will contain the next page’s identifier in thenext_page
attribute. That identifier must be provided here to retrieve the next page.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 1, "next_page": null, "page": "1", "objects": [ { "id": "u4806226", "name": "Test User", "email": "user@test.com", "role": "admin", "type": "user", }, ], }
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:
The task object has the following attributes:
-
id
: identifier used to reference task in the Task endpoint. -
state
: Current status of the request, one of:PENDING
: The task state is unknown.RECEIVED
: The task was received, waiting to start.STARTED
: The task was started and currently is in progress.
Once the task has completed it will return the result for the original request rather than a task object.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v0/accounts/15/tasks/8e3938f9-dde7-4a57-b9a2-7ad282461073'
Errors
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 cloud storage 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 cloud storage 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 cloud storage service. |
bad_gateway | 502 | Kloudless received an invalid response from the upstream cloud storage service. |
service_not_available | 503 | The upstream cloud storage service is unavailable. |
gateway_timeout | 504 | The upstream cloud storage service is unavailable. |
insufficient_storage | 507 | There is not enough free space in the cloud storage account to complete the request. |
* 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:
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.