Back to top

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 perform API 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
    • 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 Files: salesforce
    • HubSpot Files: hubspot
    • SMB: smb
    • Jive: jive
    • WebDAV: webdav
    • Adobe CQ5: cq5
    • FTP: ftp
  • Object Storage Services

    • Amazon S3: s3
    • Azure Storage: azure

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 An object listing all the ancestor folders going back to the root folder, with the most immediate ancestor listed first. May be null if not available.

  • path A human-readable path to the file in the account. May be null if unknown.

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

Upload a File 

Upload a FilePOST /accounts/{account_id}/storage/files/{?overwrite}

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/v1/accounts/123/storage/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 the Content-Length header.

Uploading large files via the url parameter should be performed asynchronously by setting the header X-Kloudless-Async: true. This will allow your client to poll for the status rather than blocking on a single request which can result in timeouts for large files.

Here is an example of a URL-based upload request:

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/v1/accounts/123/storage/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.

  • Parameters
  • overwrite
    boolean (optional) Default: False 

    Specifies 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  201Toggle
  • 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 

retrieve file metadataGET /accounts/{account_id}/storage/files/{file_id}

This will retrieve the metadata associated with the file object.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg=='
  • Response  200Toggle
  • 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 

update file metadataPATCH /accounts/{account_id}/storage/files/{file_id}

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. The parent_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 API. The parent_id must also be specified. This field is required when impersonating users since the X-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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg=='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
        "name": "new-cool-name.png",
        "parent_id": "fL2hp",
        "account": 124,
    }
  • Response  200Toggle
  • 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 

update binary file contentPUT /accounts/{account_id}/storage/files/{file_id}

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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg=='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Length: [SIZE OF FILE]
    Body
    [file data binary]
    
  • Response  200Toggle
  • 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 

get binary file contentGET /accounts/{account_id}/storage/files/{file_id}/contents

This is a direct download of the file. We proxy the download directly from the storage service so we never store your users’ files.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/12/storage/files/fZGVycGRlcnXJwCg==/contents'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers
    Content-Type: [mimetype]
    Body
    [file data binary]
    

Download a Thumbnail for a File 

Download a Thumbnail for a FileGET /accounts/{account_id}/storage/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/v1/accounts/12/storage/files/fZGVycGRlcnXJwCg/thumbnail/?size=400'
  • Parameters
  • size
    integer (optional) Default: 256 preferred 

    Specifies 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' preferred 

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

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers
    Content-Type: [mimetype]
    Body
    [file data binary]
    

Copy a File 

Copy a FilePOST /accounts/{account_id}/storage/files/{file_id}/copy

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 API. This field is required when impersonating users since the X-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/v1/accounts/12/storage/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/json
    Body
    {
        "name": "copied-file.png",
        "parent_id": "fL2hp",
    }
  • Response  201Toggle
  • 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 

Delete a FileDELETE /accounts/{account_id}/storage/files/{file_id}{?permanent}

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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg=='
  • Parameters
  • permanent
    boolean (optional) Default: False 

    If 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. If True, behaves similarly to no Trash being present and deletes the file.

    Choices: True False

  • Response  204

Create an Upload URL for a File 

Create an Upload URL for a FilePOST /accounts/{account_id}/storage/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/v1/accounts/123/storage/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: False 

    Specifies whether to overwrite existing files

    Choices: False True

    expires_in
    integer (optional) Default: 300 

    Specifies the duration of availability of the upload url.

    Choices: [1..10000]

    use_http
    boolean (optional) Default: False 

    Specifies 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

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
      "parent_id": "fL3Rlc3QucG5n==",
      "name": "test.png"
    }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "method": "put",
        "url": "https://s3.amazonaws.com/test.png?signature=XFOHi1bWEKD",
    }

Raw ID -> Kloudless ID 

Convert a Raw ID to a Kloudless Resource IDPOST /accounts/{account_id}/storage/convert_id{?retrieve_metadata}

Deprecated. Use encode_raw_id instead.

This endpoint converts IDs retrieved by connecting directly to a 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 storage 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:

Here is an example:

curl -XPOST -H 'Authorization: ApiKey [KEY]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/storage/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: False 

    Specifies whether to retrieve the resource’s metadata or not.

    Choices: False True

  • RequestToggle
  • Headers
    Authorization: ApiKey [KEY]
    Content-Type: application/json
    Body
    {
      "raw_id": "abcsdajhsdflk-lkasjhd-123",
      "type": "file"
    }
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "fL3Rlc3QucG5n=="
    }

List Recent Files 

list recent filesGET /accounts/{account_id}/storage/recent{?page_size,page,after}

This retrieves a list of recently modified 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 in the Events API.

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/v1/accounts/123/storage/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/v1/accounts/123,456,789/storage/recent'
  • Parameters
  • page_size
    number (optional) Default: 30 

    Number of objects on each page. The page_size must be between 1 and 1000.

    page
    number (optional) 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects.

    page must be greater than 0.

    after
    ISO 8601 timestamp (optional) 

    Only files updated after this time will be returned.

  • Response  200Toggle
  • 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 for filesGET /accounts/{account_id,account_id,...}/storage/search{?q,parents,lang}

Services currently supported for keyword search and the data they search are listed below:

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

  • hubspot: file name

  • jive: file name

Services currently supported for cmis search are:

  • cmis: The format is REPO_ID: QUERY, where REPO_ID is the raw repository ID and QUERY is the raw CMIS query to search the repository with.

  • alfresco: See cmis.

  • alfresco_cloud: See cmis.

Services currently supported for the parents parameter are:

  • sharepoint

  • onedrivebiz

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/v1/accounts/123/storage/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/v1/accounts/123,456,789/storage/search?q=hello+world'

To search within multiple folders for services that support the parents parameter, provide Folder IDs separated with commas as parents:

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

Search result ordering is determined by the underlying 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, or search query to run.

    parents
    string (optional) 

    Folder IDs to search on, delimited by commas.

    lang
    string (optional) Default: keyword 

    The type of search query. keyword is the default and will search the service for specific terms, using the service’s capabilities. raw will search the service using the service’s own query language.

    Choices: keyword cmis

  • Response  200Toggle
  • 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:

  1. Initialize the session

  2. Upload the parts

  3. Finalize the session

Currently multipart uploads are supported for the following services:

  • azure

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

Initialize Multipart SessionPOST /accounts/{account_id}/storage/multipart{?overwrite}

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:

    • 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. If false, 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/v1/accounts/123/storage/multipart'
  • Parameters
  • overwrite
    boolean (optional) Default: False 

    If True, an existing file with the same name will be overwritten by the uploaded file. If False, an alternate name will be chosen for the file.

    Choices: True False

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
      "parent_id": "root",
      "name": "test-big-file.iso"
    }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 543,
        "account": 123,
        "part_size": 5242880,
        "parallel_uploads": true,
    }

Retrieve Multipart Session Information 

Retrieve Multipart Session InformationGET /accounts/{account_id}/storage/multipart/{multipart_id}

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

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 543,
        "account": 123,
        "part_size": 5242880,
        "parallel_uploads": true,
    }

Upload Part 

Upload PartPUT /accounts/{account_id}/storage/multipart/{multipart_id}{?part_number}

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/v1/accounts/123/storage/multipart/543?part_number=1'
  • Parameters
  • part_number
    integer (required) Example: 1

    The 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 

Finalize Multipart SessionPOST /accounts/{account_id}/storage/multipart/{multipart_id}/complete

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/v1/accounts/123/storage/multipart/543/complete'
  • Response  201Toggle
  • 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 

Abort Multipart SessionDELETE /accounts/{account_id}/storage/multipart/{multipart_id}

This will abort the upload session and remove all uploaded parts from the upstream 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/v1/accounts/123/storage/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 and downloadable 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.

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

Create a Folder 

Create a FolderPOST /accounts/{account_id}/storage/folders/{?conflict_if_exists}

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/v1/accounts/123/storage/folders'
  • Parameters
  • conflict_if_exists
    boolean (optional) Default: False 

    If False, this will search for and return an existing folder with the same name if present, rather than attempting to create the folder. If True, 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  201Toggle
  • 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 

Retrieve Folder MetadataGET /accounts/{account_id}/storage/folders/{folder_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/folders/fTmV3IEZvbGRlcg=='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • 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 

Retrieve Folder ContentsGET /accounts/{account_id}/storage/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.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/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
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    page_size
    integer (optional) Default: 1000 

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

    All files and folders within this folder will be returned if possible. Currently supported for:

    • dropbox

    • gdrive

    • skydrive Duplicate folders may appear when paginating.

    • sharepoint Only for the root folder of a document library.

    • onedrivebiz Only for the root folder of a document library.

    ordering
    string (optional) Default: name 

    Order 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  200Toggle
  • 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 

Update Folder metadataPATCH /accounts/{account_id}/storage/folders/{folder_id}

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

The metadata of the new folder is returned.

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
      "parent_id": "faGVycGFkZXJwZGlyCg==",
      "name": "New Folder Name"
    }
  • Response  200Toggle
  • 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 

Copy a FolderPOST /accounts{account_id}/storage/folders/{folder_id}/copy

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/v1/accounts/12/storage/folders/fL3Rlc3QucG5n/copy'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
        "name": "Copied Folder",
        "parent_id": "fL2hp",
    }
  • Response  201Toggle
  • 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 

Delete a FolderDELETE /accounts/{account_id}/storage/folders/{folder_id}{?recursive,permanent}

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/v1/accounts/123/storage/folders/fTmV3IEZvbGRlcg=='
  • Parameters
  • recursive
    boolean (optional) Default: False 

    If True, folders will be deleted even if they are not empty.

    Choices: True False

    permanent
    boolean (optional) Default: False 

    If 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. If True, 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 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 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.
  • 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.

List Permissions 

List permissionsGET /accounts/{account_id}/storage/{files,folders}/{file_id,folder_id}/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/v1/accounts/123/storage/folders/fTmV3IEZvbGRlcg==/permissions'
  • Response  200Toggle
  • 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 

Set permissionsPUT /accounts/{account_id}/storage/{files,folders}/{file_id,folder_id}/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 either user or group 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 the id.

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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    [
      {
        "type": "user",
        "id": "uGWK298eguSG2==",
        "role": "writer"
      }
    ]
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "permissions": [
        {
          "id": "uGWK298eguSG2==",
          "email": "writer@test.com",
          "name": "Test Writer",
          "role": "writer",
          "type": "user"
        }
      ]
    }

Update Permissions 

Update permissionsPATCH /accounts/{account_id}/storage/{files,folders}/{file_id,folder_id}/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/v1/accounts/12/storage/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    [
      {
        "type": "user",
        "id": "uEZEKdS4Webxw==",
        "role": "writer"
      },
      {
        "type": "group",
        "id": "gNTQ==",
        "role": ""
      }
    ]
  • Response  200Toggle
  • 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:

  • dropbox

  • 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

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 

List propertiesGET /accounts/{account_id}/storage/files/{file_id}/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/v1/accounts/123/storage/files/fTmV3IEZvbGRlcg==/properties'
  • Response  200Toggle
  • 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 propertiesPATCH /accounts/{account_id}/storage/files/{file_id}/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/v1/accounts/123/storage/files/fTmV3IEZvbGRlcg==/properties'
  • Response  200Toggle
  • 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 

Delete all PropertiesDELETE /accounts/{account_id}/storage/files/{file_id}/properties

Deletes all properties for a given file.

Example request:

curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/storage/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 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.

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

Create a LinkPOST /accounts/{account_id}/storage/links/

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

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/v1/accounts/15/storage/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/v1/accounts/15/storage/links'
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
        "file_id": "fMEI0H4PP5",
        "expiration": "2015-01-01T00:00:00",
    }
  • Response  201Toggle
  • 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,
     }