Introduction to the Storage API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can begin making requests to the Storage API endpoints listed below.

Check out our Walkthrough page for an introduction to performing API requests to the Storage API, beginning with listing the root folder’s contents.

Here are the supported services, listed with service identifiers:

• File Storage Services

  • Dropbox: dropbox
  • Box: box
  • Google Drive: gdrive
  • OneDrive: skydrive
  • SharePoint Online: sharepoint
  • OneDrive for Business: onedrivebiz
  • Citrix Sharefile: sharefile
  • Egnyte: egnyte
  • Evernote: evernote
  • Jive: jive
  • SugarSync: sugarsync
  • WebDAV: webdav
  • CMIS: cmis
  • SMB: smb
  • FTP(S): ftp
  • SFTP: sftp
  • Alfresco: alfresco
  • Alfresco Cloud: alfresco_cloud
  • Adobe Experience Manager: cq5
  • SharePoint 2013+: sharepoint2013
  • Kapost: kapost
  • Asset Bank: asset_bank

• Object Storage Services

  • Amazon S3: s3
  • Azure Blob Storage: azure
  • Amazon S3 compatible: s3_compatible
    • Examples: Google Cloud Storage (Interop API), Wasabi, Minio, and others.
  • Alibaba Cloud OSS: aliyun_oss

• File data from other connector categories (billing plan requires the additional category or connectors)

  • CRM
    • Salesforce Files: salesforce
    • Hubspot Files: hubspot
    • SAVO: savo
  • Chat
    • Slack Files: slack
      • Refer to our connector guide for supported features.
    • Microsoft Teams Files: ms_teams
      • Refer to our connector guide for supported features.
  • Construction documents, images, and drawings
    • Procore: procore
      • Drawings are read-only i.e. list folder contents and download drawing PDFs.
    • PlanGrid: plangrid
    • Autodesk BIM 360 and A360 Drive: autodesk
    • Bluebeam Studio Prime: bluebeam

The Storage API has the following available object types:

• file

• folder

• upload_url

• multipart_session

• permission

• property

• link

Quickstart 

Begin by connecting a user’s account using the Kloudless OAuth authentication endpoints.

You can then retrieve the contents of the user’s root folder to begin accessing the user’s content.

If you’d like to prompt a user to select a file or folder in cloud storage to transfer data, check out our open-source File Picker on GitHub.

Files 

A File object represents metadata on a file that belongs to a user.

A file has the following attributes:

• id Unique identifier for this file. This is an encrypted version of the 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 storage service’s file ID but will not exceed 8192 characters. Some services like WebDAV can therefore have very long IDs as folder nesting increases. See the raw.id attribute for the decoded representation.

• name File name

• size File size in bytes. May be null if unknown.

• created ISO 8601 timestamp indicating when the file was created. May be null if unknown.

• modified ISO 8601 timestamp indicating when the file was last modified. May be null if unknown.

• type Will be file.

• account The id of the account that the file is associated with.

• parent An object with metadata on the parent folder. Includes the parent’s id, and name where possible. In cases where the true ID of the parent is unavailable, Kloudless may substitute any other valid ID, such as one based on the path for services such as dropbox. The metadata of the parent may be retrieved using that ID to obtain the true ID if required. Kloudless does not automatically perform this extra request for performance reasons.

• ancestors A list of objects, each representing a folder in the path from the item’s parent up to the root. The item’s parent folder is the most immediate ancestor folder and is listed first. Each ancestor object’s format is the same as the parent object format. null if unavailable.

• path A human-readable path to the file in the account. May be null if unknown.
  Note: Google Drive is one of the few cloud storage services that do not provide any path information. This field is therefore null for Google Drive files/folders.

• mime_type The content type of the file.

• downloadable A boolean indicating whether the file can be downloaded.

• raw_id Deprecated. Use raw below instead, which contains an id attribute.

• raw The raw data retrieved from the service.

• owner An object with metadata on the user who owns the file. Includes the user’s id where possible. If the id differs from the one returned by the Team endpoint, both are valid for that user. May not be present if unavailable.

• creator Similar to owner, but for the user that originally created the file. May not be present if unavailable.

• last_modifier Similar to owner, but for the user that last modified the file. May not be present if unavailable.

• api Will be storage

• ids Optional. If there are multiple IDs returned by Kloudless to refer to this object in API responses, this attribute will be an object that maps all types of IDs that could be returned to their current values. Here are the possible types of IDs:

  • default: An ID that refers to this object, based on static data unique within the upstream service, such as upstream object IDs.
  • shared: An ID that refers to this object when the object is shared and accessed via multiple users. Maintains the same value across users within the upstream service, but unique otherwise.
  • path: Similar to default, but based on the path to the file. Unique within this user’s account, but changes if the path changes.
  • version: An ID referring to a specific version of a file.

• id_type Optional. Refers to the type of id value, for objects with multiple IDs. Only present if retrieving the object’s metadata would return an ids attribute with multiple values.

• href The absolute URL to get the object’s metadata.

Upload a File 

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/v1/accounts/123/storage/files' \
    --data-binary @FILENAME

curl -X POST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"name": "test.png", "parent_id": "FL2hp", "url": "https://i.imgur.com/Y9debSL.png"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/files'

Retrieve File metadata 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft'

Rename/Move a File 

curl -X PATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"name": "test.png", "parent_id": "FL2hp"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft'

Update File content 

curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
    --data-binary @/path/to/local/file \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft'

Download a File 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft/contents'

Download a Thumbnail for a File 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft/thumbnail/?size=400'

Copy a File 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' -XPOST \
    -d '{"parent_id":"FL2hp", "name":"test.png"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft'

Delete a File 

curl -L -H 'Authorization: Bearer [TOKEN]' -XDELETE \
    'https://api.kloudless.com/v1/accounts/123/storage/files/FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft'

Create an Upload URL for a File 

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"parent_id":"fL2hp", "name": "test.png"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/upload_url'

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

• The type will be “folder”.

• The mime_type and downloadable fields will be absent.

• Folder “contents” are simply a list of the “child” files and folders present within that folder, one level down.

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.

These attributes are usually true, but will be false for certain folders such as the root ShareFile folder.

Folders also have the following additional fields:

• can_list_recursively: Indicates if the contents of this folder can be listed recursively.

Create a Folder 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"parent_id":"FL2hp", "name": "New folder"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders'

Retrieve Folder Metadata 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/F-s1lgB7cDTnjs-MCPFbWExo5RQ0uGkAKjFVwdSew'

Retrieve Folder Contents 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/FL2hp/contents'

Rename/Move a Folder 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' -XPATCH \
    -d '{"parent_id": "FL2hp", "name": "New Folder"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/F-s1lgB7cDTnjs-MCPFbWExo5RQ0uGkAKjFVwdSew'

Copy a Folder 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' -XPOST \
    -d '{"parent_id":"FL2hp", "name":"New Folder"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/F-s1lgB7cDTnjs-MCPFbWExo5RQ0uGkAKjFVwdSew'

Delete a Folder 

curl -H 'Authorization: Bearer [TOKEN]' -XDELETE \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/F-s1lgB7cDTnjs-MCPFbWExo5RQ0uGkAKjFVwdSew'

Locate Files 

List Recent Files 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/recent'

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v1/accounts/123,456,789/storage/recent'

Search 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/search?q=hello+world'

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v1/accounts/123,456,789/storage/search?q=hello+world'

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/search?q=hello+world&parents=fTmV3IEZvbGRlcg==,F-gUkFk5LSREV_W29I_PPuQ=='

Activity Monitoring 

Track changes to objects via the Activity API and webhooks.

Activity API required: These endpoints require your Kloudless subscription to include access to the Activity API.

Users and Groups 

The Team API provides information on users and groups.

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:

1. Initialize the session

2. Upload the parts

3. Finalize the session

Currently multipart uploads are supported for the following services:

• azure

• autodesk

• box

• dropbox

• egnyte

• gdrive

• s3

• aliyun_oss

• sharefile

• sharepoint

• skydrive

• onedrivebiz

Other services will have to rely on the standard upload endpoint for files.

WARNING: Incomplete or aborted multipart uploads will still occupy space in the storage account, which can incur extra storage costs for some services like Amazon S3.

Currently, parallelized multipart uploads are supported for the following services:

• azure

• s3

A multipart session has the following attributes:

• id: The ID of the new multipart session you will be interacting with. Use this ID to reference the session and upload parts.

• account: The ID of the account that the multipart session is associated with.

• size: The total size of the file being uploaded. May be null if not available.

• 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. If false, they must be uploaded serially, in order.

• complete: Boolean indicating whether the multipart session was completed. A multipart session was completed via either finalizing or aborting the multipart session.

• success: Boolean indicating whether the multipart session was completed successfully. The value would be false if the session was aborted or otherwise errors.

• type Will always be multipart_session

• api Will always be storage

• href The absolute URL to get the object’s metadata.

Initialize Multipart Session 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"parent_id":"root", "name": "test-big-file.iso"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/multipart'

Retrieve Multipart Session Information 

Upload Part 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/octet-stream' \
    -XPUT --data-binary @test-big-file.iso.part1 \
    'https://api.kloudless.com/v1/accounts/123/storage/multipart/543?part_number=1'

Finalize Multipart Session 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XPOST 'https://api.kloudless.com/v1/accounts/123/storage/multipart/543/complete'

Abort Multipart Session 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/storage/multipart/543'

Permissions 

Sharing API required: These endpoints require your Kloudless subscription to include access to the Sharing API for storage connectors.

v2: Check out the v2 Sharing API for improved collaboration features and access controls on end-user data. The initial release includes support for popular services such as SharePoint Online, OneDrive for Business, Box, G Suite, and Dropbox.

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 to reader 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 files and folders.

• gdrive

  • Supports shared files and folders.

• dropbox

  • Supports shared files and folders.

• sharepoint

  • Supports shared files and folders.
  • Currently supports only retrieval and unsharing of all permissions.

• skydrive

  • Supports shared files and folders.
  • Currently supports only reader or writer for role.

• onedrivebiz

  • Supports shared files and folders.
  • Currently supports only retrieval and unsharing of all permissions.

• s3

  • Supports buckets and objects.
  • A typical response contains only permissions mapped from ACL.
  • Enabling raw data returns the raw ACL Grant. It will be converted from xml to json format for easier parsing. In addition, a bucket’s Policy will also be returned as raw data if present.
  • Mapping of ACL Permission to Kloudless role:

    ACP Permission	Kloudless role
    "READ"	"reader"
    "WRITE"	"writer"
    "FULL_CONTROL"	"owner"
    "READ_ACP"	null
    "WRITE_ACP"	null

  • In S3, permissions are distinctly listed. e.g. If a user has both read and write permissions, they will be listed as READ and WRITE separately in the ACL. This API adopts the same logic. So in this case the response will have two permission objects with a reader and writer role for the same ID.
  • For READ_ACP and WRITE_ACP, there is no corresponding role. Enable raw data for accurate contents.
  • PUT overwrites the entire bucket/object’s ACL.
  • PATCH replaces only permissions from users or groups listed in the request body.

• sharefile

  • Supports shared folders in v2 permission format.

• smb

  • Supports listing permissions for shared files and folders in v2 permission format.

List Permissions 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/fTmV3IEZvbGRlcg==/permissions'

Set Permissions 

[
    {
        "type": "user",
        "email": "reader@test.com",
        "role": "reader"
    },
    {
        "type": "user",
        "id": "uGWK298eguSG2==",
        "role": "writer"
   }
]

curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '[{"type": "user", "id": "uGWK298eguSG2==", "role": "writer"}]'
    'https://api.kloudless.com/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg==/permissions'

Update Permissions 

[
    {
        "type": "user",
        "email": "reader@test.com",
        "role": "reader"
    },
    {
        "type": "user",
        "id": "uGWK298eguSG2==",
        "role": "writer"
   },
   {
        "type": "group",
        "id": "gNTQ==",
        "role": ""
   }
]

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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg==/permissions'

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:

• dropbox

• box

• gdrive

• cq5 (read-only)

Properties for all other services are stored by Kloudless and not set on the file or folder in the upstream service.

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

dropbox file properties are modified in groups of properties called templates. In order to modify properties for a specific template, use the format template_id|key for the Kloudless Property key.

List Properties 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/fTmV3IEZvbGRlcg==/properties'

Update Properties 

[
    {
        "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"
    }
]

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/v1/accounts/123/storage/files/fTmV3IEZvbGRlcg==/properties'

Delete all Properties 

curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/files/fTmV3IEZvbGRlcg==/properties'

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 querystring inline=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, if the user’s browser supports displaying the file within the browser, such as for images.

• 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 If true, resolves directly to the contents of the file and downloads it. If false (the default), resolves to the link generated by the underlying 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. If Kloudless does not support creating shareable links (direct: false), then Kloudless defaults to creating a direct link to download the file. Services that support the default, direct: false, and create upstream links, are:

  • azure
  • box
  • dropbox
  • egnyte
  • evernote
  • gdrive
  • jive
  • s3
  • salesforce
  • sharefile
  • skydrive

• type Will always be link

• api Will always be storage

• href The absolute URL to get the object’s metadata.

List Links 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/links'

curl -L -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v1/accounts/123,124,125/storage/links'

Create a Link 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft", "expiration": "2020-01-01T00:00:00Z"}' \
    'https://api.kloudless.com/v1/accounts/123/storage/links'

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"file_id": "FEaz9KQQePZZ0GTbtL5AH9r30-MSShp5gsOcMYDQ5Ft", "direct": true}' \
    'https://api.kloudless.com/v1/accounts/123/storage/links'

Retrieve a Link 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/links/yp0w-E_Oznw6THbnVdlX'

Update a Link 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": true, "expiration": "2020-01-01T00:00:00Z"}'
    'https://api.kloudless.com/v1/accounts/123/storage/links/yp0w-E_Oznw6THbnVdlX'

Delete a Link 

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE \
    'https://api.kloudless.com/v1/accounts/123/storage/links/yp0w-E_Oznw6THbnVdlX'

Other 

Storage Quota 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/quota'

Raw ID -> Kloudless ID 

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/storage/convert_id' \
    --data-binary '{"raw_id": "abcsdajhsdflk-lkasjhd-123", "type": "file"}'