leitzcloud API Documentation

API v2 Reference

The leitzcloud API is organized around REST. Our API is designed to have predictable, resource-oriented URLs, and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

Endpoint

https://web.leitz-cloud.com/api/2

All requests to the leitzcloud API must be performed over HTTPS. Non-HTTPS requests will be rejected.

Responses

leitzcloud uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (i.e. a required parameter was missing or invalid, the request is malformed, etc.), and codes in the 5xx range indicate an error with the leitzcloud server.

HTTP Status Code Summary

200 OK - Everything worked as expected.
304 Not Modified - The response has not changed since a previous request.
400 Bad Request - The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed.
401 Unauthorized - No valid authentication provided.
403 Forbidden - The request was refused because the authenticated user does not have access.
404 Not Found - The requested resource does not exist.
405 Method Not Allowed - An invalid HTTP method (GET, POST, etc.) was used.
409 Conflict - The request results in a conflict with the current state of the resource.
410 Gone - The requested resource did exist, but was permanently deleted.
500, 502, 503, 504 Server errors - Something went wrong on leitzcloud's end.

JSON

All API responses return a JSON object. For consistency, this is also true even in cases where the HTTP status code conveys the full response. For example, some API methods simply indicate that they were successful with an HTTP 200 status code. In those cases, the response will be:

HTTP status code: 200
Response body:
{
    "status": "ok"
}

Another case is when an HTTP 304 status code is returned, indicating that the client should use their cached response from a previous request.

HTTP status code: 304
Response body:
{
    "status": "not_modified"
}

Exact responses may be found in the details of each method.

Errors

In the case of an error, the API will use an appropriate HTTP status code in the response. JSON with details of the type of error that occurred and, when available, a human-readable description of the error will also be returned.

The following are common errors that may be encountered when working with the API:

Invalid request

HTTP status code: 400
Response body:
{
    "error": "invalid_request"
}

Access denied

HTTP status code: 401
Response body:
{
    "error": "access_denied"
}

Forbidden

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Not found

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Unknown error

HTTP status code: 500
Response body:
{
    "error": "unknown"
}

Request is using an insecure transport

HTTP status code: 400
Response body:
{
    "error": "insecure_transport",
    "error_description": "Requests MUST utilize https."
}

Request is missing a required parameter

HTTP status code: 400
Response body:
{
    "error": "invalid_request",
    "error_description": "Missing required parameter: <param>"
}

Request contains an invalid parameter value

HTTP status code: 400
Response body:
{
    "error": "invalid_request",
    "error_description": "Invalid value for parameter: <param>"
}

Date is not properly formatted

HTTP status code: 400
Response body:
{
    "error": "invalid_date_format",
    "error_description": "Invalid date format. The expected format is: YYYY-MM-DD"
}

Date/time is not properly formatted

HTTP status code: 400
Response body:
{
    "error": "invalid_datetime_format",
    "error_description": "Invalid datetime format. The expected format is: YYYY-MM-DDTHH:MM:SS"
}

License is expired

HTTP status code: 403
Response body:
{
    "error": "license_expired"
}

Trial is expired

HTTP status code: 403
Response body:
{
    "error": "trial_expired"
}

Errors specific to certain methods may be found in the method details.

Versioning

Major API versions are selected based on the endpoint URL. It is our intention to maintain backwards compatibility within a major version throughout its lifetime, except where security issues are involved. The minor API version in use can be determined by calling the version method.

Authentication

Unless otherwise noted, all leitzcloud API methods require authentication via OAuth2. Currently it supports the password and refresh token grant types, with authorization code and client credential grants coming in the near future.

The OAuth2 provider is not specific to an API version. For details on obtaining, refreshing, and revoking OAuth2 access tokens see the OAuth2 documentation.

General

Request a password reset token

POST /api/2/reset_password

Fields

Required

email: the email address of the user initiating the password reset.
destination: the destination URL to which the user should be sent to confirm the password reset. The destination's first-level domain name must match either the domain in the API request or the hostname of the user's organization. It must also contain a "{token}" placeholder, which will be replaced with the generated password reset token.

Response

HTTP status code: 200

Confirm a password reset token

Confirming a reset token will return new OAuth2 access tokens, which may then be used to set the user's password via the update person method.

POST /api/2/reset_password/confirm

Fields

Required

token: the password reset token.

Response

HTTP status code: 200
Response body:
{
    "access_token": "<access_token>",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "<refresh_token>",
    "scope": "full"
}

Errors

Password reset token expired

HTTP status code: 401
Response body:
{
    "error": "password_reset_token_expired"
}

Version

The version method returns the exact API version available in the format <major>.<minor>.<revision>. Authentication is not required.

GET /api/2/version

Response

HTTP status code: 200
Response body:
{
    "version": "2.0.9"
}

File system

Root object

Attributes

type string

"root"
id integer

The unique identifier of the root
name string

The name of the root
path string

"/"
is_locked boolean

Whether the root is locked
root_type string

The type of the root: "sync", "share", or "backup"
space_used integer

The total size of the root in bytes
space_used_formatted string

The total size of the root in human friendly formatting
children list

A list of child files and folders
permissions list

A list of the authenticated user's permissions on the root.
hash string

A hash of the root metadata used for results caching

Example

{
    "ancestors": [
        ...ancestor folders and/or root...
    ],
    "children": [
        ...child files and folders...
    ],
    "hash": "<hash>",
    "id": 1,
    "is_locked": false,
    "name": "Example Files",
    "path": "/",
    "permissions": [
        "FILE_VIEW",
        "FILE_READ",
        "FILE_WRITE"
    ],
    "root_type": "sync",
    "space_used": 10000,
    "space_used_formatted": "10k",
    "type": "root"
}

File object

Attributes

type string

"file"
id integer

The unique identifier of the file
revision_id integer

The unique revision identifier of the file
root_id integer

The identifier of the root containing the file
name string

The file name
path string

The absolute path of the file within the root
is_deleted boolean

Whether the file is deleted
created string

The date/time in UTC the file was created in the format YYYY-MM-DDTHH:MM:SS
modified string

The date/time in UTC the file was last modified in the format YYYY-MM-DDTHH:MM:SS
size integer

The size of the file in bytes
size_formatted string

The size of the file in human friendly formatting
is_locked boolean

Whether the file is locked
permissions list

A list of the authenticated user's permissions on the file.
ancestors list

A list of the file's ancestors in order of increasing depth. Depending on context the first entry may be the top-level root object.

Example

{
    "ancestors": [
        ...ancestor folders and/or root...
    ],
    "created": "2015-01-01T01:02:03",
    "id": 1,
    "is_deleted": false,
    "is_locked": false,
    "modified": "2015-01-01T02:03:04",
    "name": "file.ext",
    "path": "/path/to/file.ext",
    "permissions": [
        "FILE_VIEW",
        "FILE_READ",
        "FILE_WRITE"
    ],
    "revision_id": 1,
    "root_id": 1,
    "size": 12205,
    "size_formatted": "11.92k",
    "type": "file"
}

Folder object

Attributes

type string

"folder"
id integer

The unique identifier of the folder
root_id integer

The identifier of the root containing the folder
name string

The folder name
path string

The absolute path of the folder within the root
is_deleted boolean

Whether the folder is deleted
is_locked boolean

Whether the folder is locked
children list

A list of child files and folders
permissions list

A list of the authenticated user's permissions on the folder.
hash string

A hash of the folder metadata used for results caching
ancestors list

A list of the folder's ancestors in order of increasing depth. Depending on context the first entry may be the top-level root object.

Example

{
    "children": [
        ...child files and folders...
    ],
    "hash": "<hash>",
    "id": 1,
    "is_deleted": false,
    "is_locked": false,
    "name": "name",
    "path": "/path/to/name",
    "permissions": [
        "FILE_VIEW",
        "FILE_READ",
        "FILE_WRITE"
    ],
    "root_id": 1,
    "type": "folder"
}

Revision object

Attributes

type string

"revision"
id integer

The unique identifier of the revision
file_id integer

The unique identifier of the file
root_id integer

The identifier of the root containing the revision
created string

The date/time in UTC the revision was created in the format YYYY-MM-DDTHH:MM:SS
modified string

The date/time in UTC the revision was last modified in the format YYYY-MM-DDTHH:MM:SS
full_size integer

The size of the revision's full image file, if applicable, in bytes
full_size_formatted string

The size of the revision's full image file, if applicable, in human friendly formatting
delta_size integer

The size of the revision's delta image file, if applicable, in bytes
delta_size_formatted string

The size of the revision's delta image file, if applicable, in human friendly formatting
file_size integer

The size of the file at time of this revision in bytes
file_size_formatted string

The size of the file at time of this revision in human friendly formatting

Example

{
    "created": "2019-12-05T14:12:11",
    "delta_size": 4096,
    "delta_size_formatted": "4.00 KB",
    "file_id": 1953,
    "file_size": 14679,
    "file_size_formatted": "14.33 KB",
    "full_size": 11200,
    "full_size_formatted": "10.94 KB",
    "id": 3747,
    "modified": "2019-12-05T14:12:11",
    "root_id": 1,
    "type": "revision"
}

Root space usage object

Attributes

type string

"root_space_usage"
del_file_count integer

Number of deleted files
del_revision_count integer

Number of deleted revisions
deleted_size integer

Space usage of deleted files in bytes
deleted_size_formatted string

Space usage of deleted files in human friendly formatting
file_count integer

Total number of files
head_size integer

Space usage of non-deleted files in bytes
head_size_formatted string

Space usage of non-deleted files in human friendly formatting
physical_size integer

Total space usage in bytes
physical_size_formatted string

Total space usage in human friendly formatting
revision_count integer

Number of revisions
revision_size integer

Space usage of revisions in bytes
revision_size_formatted string

Space usage of revisions in human friendly formatting
root_count integer

The total number of roots included in the usage metrics

Example

{
    "del_file_count": 5,
    "del_revision_count": 5,
    "deleted_size": 395168,
    "deleted_size_formatted": "385.91 KB",
    "file_count": 504,
    "head_size": 41533273,
    "head_size_formatted": "39.61 MB",
    "physical_size": 43199769,
    "physical_size_formatted": "41.20 MB",
    "revision_count": 2275,
    "revision_size": 1271328,
    "revision_size_formatted": "1.21 MB",
    "root_count": 21,
    "type": "root_space_usage"
}

File methods

Get file metadata

GET /api/2/files/<root_id>/<file_id>

Query Parameters

include_ancestors: whether to include the file's ancestors in the response. "true" or "false". Default "false".
include_permissions: whether to include the user's file permissions in the response. "true" or "false". Default "false".

Response

HTTP status code: 200
Response body:
{
    ...a file object...
}

Download a file

GET /api/2/files/<root_id>/<file_id>/download
GET /api/2/files/<root_id>/<file_id>/view

Whether the file is downloaded via the download endpoint or view endpoint determines the Content-Disposition in the response -- attachment or inline, respectively.

Response

HTTP status code: 200
Response body:
<binary file data>

Share a file

POST /api/2/files/<root_id>/<file_id>/share

POST Fields

login_required: whether users must log in to access the share. "true" or "false". Default "false".
expires: a date in the format YYYY-MM-DD the share expires. Defaults to no expiration.
subscribers: a comma-separated list of subscribers by email address.
notify_subscribers: "true" or "false". Default "false".
download_limit: the total number of downloads allowed for the share. Defaults to unlimited.
download_notify: whether you want to be notified of downloads. "true" or "false". Default "false".

Response

HTTP status code: 200
Response body:
{
    ...a file share link object...
}

Rename a file

POST /api/2/files/<root_id>/<file_id>/rename

POST Fields

name: the new file name. Required.

Errors

Invalid file name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Invalid file extension

HTTP status code: 400
Response body:
{
    "error": "invalid_extension"
}

A file with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Move a file

POST /api/2/files/<root_id>/<file_id>/move

POST Fields

to_folder_id: the destination folder ID. To move to the root, omit this parameter.

Errors

A file with the same name already exists in the destination

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Lock a file

POST /api/2/files/<root_id>/<file_id>/lock

POST Fields

duration: the number of minutes after which the lock will be automatically released.

Response

HTTP status code: 200

Unlock a file

POST /api/2/files/<root_id>/<file_id>/unlock

Response

HTTP status code: 200

Delete a file

POST /api/2/files/<root_id>/<file_id>/delete

Response

HTTP status code: 200

List file revisions

GET /api/2/files/<root_id>/<file_id>/revisions

Query Parameters

include_related: whether to include all revisions of all the files that have the same current path as the given file (i.e. all revisions that would replace the given file if restored). "true" or "false". Default "false".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size revision objects...
    ],
    "total": 42
}

page: the page given in the method call or 1.
page_size: the page_size given in the method call or 20.
max_page: the total number of result pages.
results: a list of revision objects.
total: the total number of result records available.

Get revision metadata

GET /api/2/files/<root_id>/<file_id>/revisions/<revision_id>

Response

HTTP status code: 200
Response body:
{
    ...a revision object...
}

Download a revision

GET /api/2/files/<root_id>/<file_id>/revisions/<revision_id>/download
GET /api/2/files/<root_id>/<file_id>/revisions/<revision_id>/view

Response

HTTP status code: 200
Response body:
<binary file data>

Whether the revision is downloaded via the download endpoint or view endpoint determines the Content-Disposition in the response -- attachment or inline, respectively.

Folder methods

Get folder metadata

GET /api/2/files/<root_id>/folder/<folder_id>

Query Parameters

include_ancestors: whether to include the folder's ancestors in the response. "true" or "false". Default "false".
include_children: whether to include the folder's children in the response. "true" or "false". Default "true".
include_deleted: whether to include deleted children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
include_permissions: whether to include the user's file and folder permissions in the response. "true" or "false". Default "false".
hash: the hash value returned by the last call to this method. Only used when include_children is "true".

Response

HTTP status code: 200
Response body:
{
    ...a folder object...
}

children is a list of file and folder metadata objects within the folder. It is only present when include_children is "true".

The hash value represents a signature for the response data. If the hash value in the response would be identical to the hash value passed by the client, then HTTP 304 Not Modified will be returned. hash is only present when include_children is "true".

Get metadata for a folder's children

GET /api/2/files/<root_id>/folder/<folder_id>/children

Returns metadata for the immediate children of a folder with options for sorting and pagination.

Query Parameters

include_deleted: whether to include deleted children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
include_permissions: whether to include the user's file and folder permissions in the response. "true" or "false". Default "false".
sort_by: the field on which to sort: "name", "modified", or "size". Default "name".
sort_order: the sort direction: "asc" or "desc". Default "asc".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size file and folder objects...
    ],
    "total": 42
}

Upload a file to a folder

POST /api/2/files/<root_id>/folder/<folder_id>/upload

POST Fields

file: Required.

Response

HTTP status code: 200
Response body:
{
    ...file metadata...
}

Errors

No file received

HTTP status code: 400
Response body:
{
    "error": "no_file_received",
    "error_description": "Missing required file: file"
}

File rejected due to company policy

HTTP status code: 409
Response body:
{
    "error": "policy_error"
}

Invalid file name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Invalid file extension

HTTP status code: 400
Response body:
{
    "error": "invalid_extension"
}

A file with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Create a subfolder

POST /api/2/files/<root_id>/folder/<folder_id>/create_folder

POST Fields

name: the new folder name. Required.

Response

HTTP status code: 200
Response body:
{
    ...folder metadata...
}

Errors

Invalid folder name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Folder name is too long

HTTP status code: 400
Response body:
{
    "error": "name_too_long"
}

A folder with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Download a folder

GET /api/2/files/<root_id>/download
GET /api/2/files/<root_id>/folder/<folder_id>/download

Query Parameters

Optional

file_ids: a comma-separated list of file IDs to include in the download. Must be direct children of the resource specified in the request.
folder_ids: a comma-separated list of folder IDs to include in the download. Must be direct children of the resource specified in the request.

If either file_ids or folder_ids is present, the download will include only the items specified.

Response

HTTP status code: 200
Response body:
<binary zip file data>

Share a folder

POST /api/2/files/<root_id>/folder/<folder_id>/share

POST Fields

login_required: whether users must log in to access the share. "true" or "false". Default "false".
expires: a date in the format YYYY-MM-DD the share expires. Defaults to no expiration.
subscribers: a comma-separated list of subscribers by email address.
notify_subscribers: "true" or "false". Default "false".
download_limit: the total number of downloads allowed for the share. Defaults to unlimited.
download_notify: whether you want to be notified of downloads. "true" or "false". Default "false".

Response

HTTP status code: 200
Response body:
{
    ...a folder share link object...
}

Rename a folder

POST /api/2/files/<root_id>/folder/<folder_id>/rename

POST Fields

name: the new folder name. Required.

Errors

Invalid folder name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Folder name is too long

HTTP status code: 400
Response body:
{
    "error": "name_too_long"
}

A folder with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Move a folder

POST /api/2/files/<root_id>/folder/<folder_id>/move

POST Fields

to_folder_id: the destination folder ID. To move to the root, omit this parameter.

Errors

A folder with the same name already exists in the destination

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Lock a folder

POST /api/2/files/<root_id>/folder/<folder_id>/lock

POST Fields

duration: the number of minutes after which the lock will be automatically released.

Response

HTTP status code: 200

Unlock a folder

POST /api/2/files/<root_id>/folder/<folder_id>/unlock

Response

HTTP status code: 200

Delete a folder

POST /api/2/files/<root_id>/folder/<folder_id>/delete

Response

HTTP status code: 200

Root methods

Get root metadata

GET /api/2/files/<root_id>

Query Parameters

include_children: whether to include the root's children in the response. "true" or "false". Default "true".
include_deleted: whether to include deleted children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
include_permissions: whether to include the user's root, file, and folder permissions in the response. "true" or "false". Default "false".
hash: the hash value returned by the last call to this method. Only used when include_children is "true".

Response

HTTP status code: 200
Response body:
{
    ...a root object...
}

Possible values for root_type are "sync", "share", and "backup".

children is a list of file and folder metadata objects at the top level of the root. It is only present when include_children is "true".

HTTP status code: 304

Get metadata for a root's children

GET /api/2/files/<root_id>/children

Returns metadata for the immediate children of a root with options for sorting and pagination.

Query Parameters

include_deleted: whether to include deleted children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
include_permissions: whether to include the user's file and folder permissions in the response. "true" or "false". Default "false".
sort_by: the field on which to sort: "name", "modified", or "size". Default "name".
sort_order: the sort direction: "asc" or "desc". Default "asc".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size file and folder objects...
    ],
    "total": 42
}

Upload a file to a root

POST /api/2/files/<root_id>/upload

POST Fields

file: Required.

Response

HTTP status code: 200
Response body:
{
    ...file metadata...
}

Errors

No file received

HTTP status code: 400
Response body:
{
    "error": "no_file_received",
    "error_description": "Missing required file: file"
}

File rejected due to company policy

HTTP status code: 409
Response body:
{
    "error": "policy_error"
}

Invalid file name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Invalid file extension

HTTP status code: 400
Response body:
{
    "error": "invalid_extension"
}

A file with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Create a folder in a root

POST /api/2/files/<root_id>/create_folder

POST Fields

name: the new folder name. Required.

Response

HTTP status code: 200
Response body:
{
    ...folder metadata...
}

Errors

Invalid folder name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Folder name is too long

HTTP status code: 400
Response body:
{
    "error": "name_too_long"
}

A folder with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Search files and folders

GET /api/2/files/<root_id>/search

Query Parameters

q: the search term. Required.

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...file and folder metadata...
    ]
}

List recently modified files

GET /api/2/files/<root_id>/modified_since

Query Parameters

since: a date/time in UTC in the format YYYY-MM-DDTHH:MM:SS. Required.
include_deleted: "true" or "false". Default "true".

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...file metadata...
    ]
}

Lock a root

POST /api/2/files/<root_id>/lock

POST Fields

duration: the number of minutes after which the lock will be automatically released.

Response

HTTP status code: 200

Unlock a root

POST /api/2/files/<root_id>/unlock

Response

HTTP status code: 200

Errors

The following errors may occur for any file system method and are not explicity mentioned in the method descriptions.

Authenticated user does not have access to the root

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Root, Folder, or File does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Root, Folder, or File is locked

HTTP status code: 409
Response body:
{
    "error": "resource_locked"
}

Root is no longer accessible because it was deleted

HTTP status code: 410
Response body:
{
    "error": "root_deleted",
    "error_description": "Root was previously deleted."
}

The file server is busy or temporarily unavailable

HTTP status code: 503
Response body:
{
    "error": "temporarily_unavailable",
    "error_description": "Service is temporarily unavailable.""
}

Organization

Organization object

An organization represents a collection people, machines, roots, and other child organizations. Access control, policies, and most system settings are applied at the organization level.

Attributes

type string

"organization"
id integer

The unique identifier for the organization
parent_id integer

The unique identifier of the parent organization
name string

The organization name
slug string

The URL friendly organization name
description string

A description of the organization
email string

The organization's contact email address
hostname string

The hostname your organization's agents will use to connect
policy object

A policy object
created string

The date/time in UTC the organization was created in the format YYYY-MM-DDTHH:MM:SS
email_server_id integer
bandwidth_throttle integer
throttle_exception_start string
throttle_exception_end string
throttle_exception_dow list of integers
throttle_exception_days string
throttle_exception_throttle integer
throttled boolean

Whether bandwidth throttling is enabled for the organization
active boolean

Whether the organization is active
plan_id integer
trial_until string

The date/time in UTC the organization's trial period expires in the format YYYY-MM-DDTHH:MM:SS
subscription_uuid string
share_disclaimer string
default_encryption integer
email_templates boolean
privacy_mode boolean

Whether privacy mode is enabled for the organization

Example

{
    "active": true,
    "bandwidth_throttle": null,
    "created": "2013-10-08T05:45:40",
    "default_encryption": 1,
    "description": "",
    "email": "organization@example.com",
    "email_server_id": null,
    "email_templates": false,
    "hostname": "",
    "id": 2,
    "name": "Example Organization",
    "parent_id": 1,
    "plan_id": null,
    "policy": {
        ...a policy object...
    },
    "privacy_mode": false,
    "share_disclaimer": null,
    "slug": "example-organization",
    "subscription_uuid": null,
    "throttle_exception_days": null,
    "throttle_exception_dow": null,
    "throttle_exception_end": null,
    "throttle_exception_start": null,
    "throttle_exception_throttle": null,
    "throttled": false,
    "trial_until": null,
    "type": "organization"
}

Policy object

Attributes

type string

"policy"
company_id integer

The identifier of the organization to which the policy belongs
ad_enabled boolean
admin_browse_files boolean

Whether administrators can browse files
admin_browse_remote boolean

Whether administrators can browser remote files
admin_create_users boolean

Whether administrators can create users
backups_enabled boolean

Whether backups are enabled
branding_enabled boolean

Whether custom branding is enabled
change_password_frequency
deactivate_token_frequency
excluded_extensions string

A comma-delimited list of file extensions not allowed to be uploaded
file_server_enabled boolean
locked_extensions string

A comma-delimited list of file extensions
max_file_size integer

The maximum uploaded file size in XX
monthly_cost_cents integer
monthly_cost_currency string
num_orgs_maximum integer

The maximum number of child organizations allowed
num_users_maximum integer

The maximum number of users allowed
psa_enabled boolean

Whether PSA integration is enabled
purge_deleted boolean

Whether deleted files are automatically purged
purge_deleted_frequency

The frequency at which deleted files are automatically purged
require_mobile_lock boolean

Whether mobile app users are required to use a PIN lock
require_two_step_auth boolean

Whether users are required to enable two-step authentication
secure_shares boolean

Whether file shares are required to be private
service_plans_enabled boolean
space_quota integer

The maximum space allowed to be used by the organization
space_quota_formatted integer

The maximum space allowed to be used by the organization in human friendly formatting
trial_length_days integer
trim_revisions boolean

Whether file revisions are automatically trimmed
trim_revisions_x
user_create_backups boolean

Whether users are allowed to create backup roots
user_create_shares boolean

Whether users are allowed to share files
user_lock_files boolean

Whether users are allowed to lock files
user_purge_deleted boolean

Whether users are allowed to purge deleted files
user_trim_revisions boolean

Whether users are allowed to trim file revisions
webdav_enabled boolean

Whether WebDAV access is enabled

Example

{
    "ad_enabled": true,
    "admin_browse_files": true,
    "admin_browse_remote": true,
    "admin_create_users": true,
    "backups_enabled": true,
    "branding_enabled": true,
    "change_password_frequency": null,
    "company_id": 2,
    "deactivate_token_frequency": "",
    "excluded_extensions": ".$$,.$db,.113,.3g2,.3gp,.3gp2,.3gpp,.3mm,.a,.abf,.abk,.afm,.ani,.ann,.asf,.avi,.avs,.bac,.bak,.bck,.bcm,.bdb,.bdf,.bkf,.bkp,.bmk,.bsc,.bsf,.cab,.cf1,.chm,.chq,.chw,.cnt,.com,.cpl,.cur,.dev,.dfont,.dll,.dmp,.drv,.dv,.dvd,.dvr,.dvr-ms,.eot,.evt,.exe,.ffa,.ffl,.ffo,.ffx,.flc,.flv,.fnt,.fon,.ftg,.fts,.fxp,.gid,.grp,.hdd,.hlp,.hxi,.hxq,.hxr,.hxs,.ico,.idb,.idx,.ilk,.img,.inf,.ini,.ins,.ipf,.iso,.isp,.its,.jar,.jse,.kbd,.kext,.key,.lex,.lib,.library-ms,.lnk,.log,.lwfn,.m1p,.m1v,.m2p,.m2v,.m4v,.mem,.mkv,.mov,.mp2,.mp2v,.mp4,.mpe,.mpeg,.mpg,.mpv,.mpv2,.msc,.msi,.msm,.msp,.mst,.ncb,.nt,.nvram,.o,.obj,.obs,.ocx,.old,.ost,.otf,.pch,.pf,.pfa,.pfb,.pfm,.pnf,.pol,.pref,.prf,.prg,.prn,.pvs,.pwl,.qt,.rdb,.reg,.rll,.rox,.sbr,.scf,.scr,.sdb,.shb,.suit,.swf,.swp,.sys,.theme,.tivo,.tmp,.tms,.ttc,.ttf,.v2i,.vbe,.vga,.vgd,.vhd,.video,.vmc,.vmdk,.vmsd,.vmsn,.vmx,.vxd,.win,.wpk",
    "file_server_enabled": false,
    "locked_extensions": ".doc,.docx,.xls,.xlsx,.ppt,.pptx,.pdf,.txt,.xlsb,.xlsm,.csv,.docm,.dotx,.dotm,.pub,.wpd,.odt,.ott,.oth,.odm,.ots,.odp,.odg,.otp,.odf,.oxt,.odc,.ods,.vdx,.vsx,.vtx,.one",
    "max_file_size": 1,
    "monthly_cost_cents": 0,
    "monthly_cost_currency": "",
    "num_orgs_maximum": 10,
    "num_users_maximum": 0,
    "psa_enabled": true,
    "purge_deleted": false,
    "purge_deleted_frequency": "",
    "require_mobile_lock": true,
    "require_two_step_auth": false,
    "secure_shares": false,
    "service_plans_enabled": false,
    "space_quota": "1073741824",
    "trial_length_days": 30,
    "trim_revisions": false,
    "trim_revisions_x": "",
    "type": "policy",
    "user_create_backups": true,
    "user_create_shares": true,
    "user_lock_files": true,
    "user_purge_deleted": false,
    "user_trim_revisions": false,
    "webdav_enabled": true
}

Organization usage object

Attributes

type string

"organization_usage"
backup_space_usage integer

A root space usage object of backup usage metrics
counts boolean

An organization usage counts object
team_share_space_usage integer

A root space usage object of team share usage metrics
total_space_usage integer

A root space usage object of total usage metrics for all roots
user_space_usage integer

A root space usage object of user root usage metrics

Example

{
    "backup_space_usage": {
        ...a root space usage object...
    },
    "counts": {
        ...an organization usage counts object...
    },
    "team_share_space_usage": {
        ...a root space usage object...
    },
    "total_space_usage": {
        ...a root space usage object...
    },
    "type": "organization_usage",
    "user_space_usage": {
        ...a root space usage object...
    }
}

Organization usage counts object

Attributes

type string

"organization_usage_counts"
accounts integer

Total number of accounts
admin_accounts integer

Number of admin accounts
groups integer

Number of groups
guests integer

Number of guests
machines integer

Number of machines
organizations integer

Number of organizations

Example

{
    "accounts": 11,
    "admin_accounts": 5,
    "groups": 8,
    "guests": 4,
    "machines": 6,
    "organizations": 7,
    "type": "organization_usage_counts"
}

Organization methods

Get an organization

GET /api/2/organization/<organization_id>
GET /api/2/organization/<license_key>

Response

HTTP status code: 200
Response body:
{
    ...an organization object...
}

Update organization license key

POST /api/2/organization/<company_id>/license

POST Fields

Required

license_key: the license key.

Response

Returns the updated organization

HTTP status code: 200
Response body:
{
    ...an organization object...
}

Create an organization

POST /api/2/organization/<organization_id>/organizations/create

POST Fields

Required

name: the organization name.
email: the organization's contact email address.
hostname: a unique hostname for the organization, used in links to resources and shares. This should be only the third-level portion of the hostname (e.g. "company" in "company.example.com"). Not required for single host configurations.
slug: a unique, URL-friendly organization identifier. For example, an organization named "Widgets, Ltd." may have the slug "widgets-ltd".

Optional

description: a description of the organization. Defaults to empty.
parent_id: the ID of the parent organization. Defaults to the root organization.
trial_until: a date/time in the format YYYY-MM-DDTHH:MM:SS the organization trial period expires. Defaults to no trial period.
share_disclaimer:
space_quota: space quota in bytes. Default 2199023255552.
max_file_size: max file size in MB. Default 300.
excluded_extensions: excluded extensions. Default ".$$,.$db,.113,.3g2,.3gp,.3gp2,.3gpp,.3mm,.a,.abf,.abk,.afm,.ani,.ann,.asf,.avi,.avs,.bac,.bak,.bck,.bcm,.bd2,.bdb,.bdf,.bkf,.bkp,.bmk,.bsc,.bsf,.cab,.cf1,.chm,.chq,.chw,.cnt,.com,.cpl,.cur,.dbs,.dev,.dfont,.dll,.dmp,.drv,.dv,.dvd,.dvr,.dvr-ms,.eot,.evt,.exe,.ffa,.ffl,.ffo,.ffx,.flc,.flv,.fnt,.fon,.ftg,.fts,.fxp,.gid,.grp,.hdd,.hlp,.hxi,.hxq,.hxr,.hxs,.ico,.idb,.idx,.ilk,.img,.inf,.ini,.ins,.ipf,.iso,.isp,.its,.jar,.jse,.kbd,.kext,.key,.lex,.lib,.library-ms,.lnk,.log,.lwfn,.m1p,.m1v,.m2p,.m2v,.m4v,.mem,.mkv,.mov,.mp2,.mp2v,.mp4,.mpe,.mpeg,.mpg,.mpv,.mpv2,.msc,.msi,.msm,.msp,.mst,.ncb,.nt,.nvram,.o,.obj,.obs,.ocx,.old,.ost,.otf,.pch,.pd6,.pf,.pfa,.pfb,.pfm,.pnf,.pol,.pref,.prf,.prg,.prn,.pst,.pvs,.pwl,.QBA,.QBA.TLG,.QBW,.QBW.TLG,.qt,.rdb,.reg,.rll,.rox,.sbr,.scf,.scr,.sdb,.shb,.suit,.swf,.swp,.sys,.theme,.tivo,.tmp,.tms,.ttc,.ttf,.v2i,.vbe,.vga,.vgd,.vhd,.video,.vmc,.vmdk,.vmsd,.vmsn,.vmx,.vxd,.win,.wpk".
user_trim_revisions: allow users to erase revisions? Default "false".
trim_revisions: auto-erase revisions? Default "false".
trim_revisions_x: erase revisions for files unchanged after a certain number of days. Default.
user_purge_deleted: allow users to erase deleted files? Default "false".
purge_deleted: auto-erase deleted files? Default "false".
purge_deleted_frequency: erase deleted files after a certain number of days. Default never.
deactivate_token_frequency: deactivate API tokens after a certain number of days. Default 30.
user_create_backups: allow users to create their own backups? Default "true".
user_create_shares: allow users to share files? Default "true".
secure_shares: force new share links to require login? Default "false".
user_overwrite_collisions: allow users to overwrite collisions? Default "false".
user_bulk_resolve_warnings: allow users to resolve multiple warnings at once? Default "false".
user_lock_files: allow users to lock files? Default "false".
locked_extensions: use filesystem permissions to enforce locks on. Default ".doc,.docx,.xls,.xlsx,.ppt,.pptx,.pdf,.txt,.xlsb,.xlsm,.csv,.docm,.dotx,.dotm,.pub,.wpd,.odt,.ott,.oth,.odm,.ots,.odp,.odg,.otp,.odf,.oxt,.odc,.ods,.vdx,.vsx,.vtx,.one".
admin_browse_files: let organization admins browse user files? Default "true".
admin_browse_remote: let organization admins browse remote files? Default "true".
admin_create_users: let organization admins create users? Default "true".
change_password_frequency: force password change after a certain number of days. Default never.
require_two_step_auth: require two-step authentication? Default "false".
num_users_maximum: max number of users. Default none.
num_orgs_maximum: max number of suborganizations. Default 10.
backups_enabled: enable backup creation? Default "true".
branding_enabled: enable branding support? Default "true".
webdav_enabled: enable WebDAV support? Default "true".
psa_enabled: enable PSA support? Default "true".
ad_enabled: enable directory server authentication support? Default "true".
file_server_enabled: enable File Server Enablement? Default "true".
trial_length_days: trial length in days. Default 30.
service_plans_enabled: enable service plans? Default "false".
require_mobile_lock: require passcode lock on mobile devices? Default "false".
web_preview_enabled: allow users to preview files on the web? Default "true".

Response

Returns the created organization.

HTTP status code: 200
Response body:
{
    ...an organization object...
}

Update an organization

POST /api/2/organization/<organization_id>/update

Response

Returns the updated organization.

HTTP status code: 200
Response body:
{
    ...an organization object...
}

Disable an organization

POST /api/2/organization/<organization_id>/disable

Enable an organization

POST /api/2/organization/<organization_id>/enable

Delete an organization

POST /api/2/organization/<organization_id>/delete

Update an organization's policy

POST /api/2/organization/<organization_id>/policy/update

Response

Returns the updated organization.

HTTP status code: 200
Response body:
{
    ...an organization object...
}

List an organization's child organizations

GET /api/2/organization/<organization_id>/organizations

Query Parameters

offset: zero-based offset from which to start listing child organizations. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 organization objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of organization objects.
total: the total number of child organizations.

Root methods

List an organization's roots

GET /api/2/organization/<organization_id>/roots

Query Parameters

offset: zero-based offset from which to start listing roots. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 root objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of root objects.
total: the total number of roots.

Get a root

GET /api/2/organization/<organization_id>/root/<root_id>

Response

HTTP status code: 200
Response body:
{
    ...a root object...
}

List an organization's shares

GET /api/2/organization/<organization_id>/shares

Query Parameters

offset: zero-based offset from which to start listing shares. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 root objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of root objects.
total: the total number of shares.

Create a share

POST /api/2/organization/<organization_id>/shares/create

POST Fields

Required

name: the share name.

Optional

description: a description of the share. Defaults to empty.
auto_lock: enable auto-locking of files in supported applications? Default "false".
notify: notify new subscribers? Default "true".
subscribers: a JSON list of three-tuples with the first value being a person ID, the second value being a machine ID or subscription type, "all", "future", "web", or "webdav", and the third value being an access role. Example: [[1, "all", "COLLABORATOR"], [2, "web", "COLLABORATOR"]]
group_subscribers: a JSON list of three-tuples with the first value being a group ID, the second value being a subscription type, "web", "webdav", or "machines", and the third value being an access role. Example: [[1, "web", "COLLABORATOR"], [2, "machines", "COLLABORATOR"]]
external_subscribers: a JSON list of external subscriber email addresses. These must be existing accounts in a different organization. Example: ["john@example.com", "jane@example.com"]

Response

Returns the created share.

HTTP status code: 200
Response body:
{
    ...a root object...
}

Get a share

GET /api/2/organization/<organization_id>/share/<root_id>

Response

HTTP status code: 200
Response body:
{
    ...a root object...
}

Update a share

POST /api/2/organization/<organization_id>/share/<root_id>/update

POST Fields

Optional

company_id: a company ID to which the share will be moved.
name: the share name.
description: a description of the share.
auto_lock: enable auto-locking of files in supported applications?
notify: notify new subscribers?

Response

Returns the updated share.

HTTP status code: 200
Response body:
{
    ...a root object...
}

List share subscribers

GET /api/2/organization/<organization_id>/share/<root_id>/subscribers

Query Parameters

include_from_group: include individual subscribers from subscribed groups? Defaults to "false".

Response

HTTP status code: 200
Response body:
{
    "external_subscribers": {"one@example.com": "invited", "two@example.com": "accepted"},
    "from_group": [[2, "web", "COLLABORATOR"], [2, "webdav", "COLLABORATOR"], [2, "future", "COLLABORATOR"]],
    "group_subscribers": [[1, "web", "COLLABORATOR"], [1, "webdav", "COLLABORATOR"], [1, "machines", "COLLABORATOR"]],
    "subscribers": [[1, "web", "COLLABORATOR"], [3, "web", "COLLABORATOR"], [3, "future", "COLLABORATOR"]]
}

external_subscribers: a dictionary of external subscribers keyed by email address with values of "invited", "accepted", or "declined" indicating the invitee's response.
from_group: a list of three-tuples with the first value being a person ID, the second value being a machine ID or subscription type, "web", "webdav", or "future", and the third value being an access role.
group_subscribers: a list of three-tuples with the first value being a group ID, the second value being a subscription type, "web", "webdav", or "machines", and the third value being an access role.
subscribers: a list of three-tuples with the first value being a person ID, the second value being a machine ID or subscription type, "future", "web", or "webdav", and the third value being an access role.

Update share subscribers

POST /api/2/organization/<organization_id>/share/<root_id>/subscribers/update

POST Fields

Optional

subscribers: a JSON list of three-tuples with the first value being a person ID, the second value being a machine ID or subscription type, "all", "future", "web", or "webdav", and the third value being an access role. Example: [[1, "all", "COLLABORATOR"], [2, "web", "COLLABORATOR"]]
group_subscribers: a JSON list of three-tuples with the first value being a group ID, the second value being a subscription type, "web", "webdav", or "machines", and the third value being an access role. Example: [[1, "web", "COLLABORATOR"], [2, "machines", "COLLABORATOR"]]
external_subscribers: a JSON list of tuples with the first value being an email address and the second value being an access role. Example: [["john@example.com", "COLLABORATOR"], ["jane@example.com", "VIEWER"]]
remove_files: remove files from unsubscribed agents? Default "false".

Response

HTTP status code: 200

Delete a share

POST /api/2/organization/<organization_id>/share/<root_id>/delete

POST Fields

Optional

remove_files: remove files from subscribed agents? Default "false".

Response

HTTP status code: 200

Machine methods

List an organization's machines

GET /api/2/organization/<organization_id>/machines

Query Parameters

offset: zero-based offset from which to start listing machines. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 machine objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of machine objects.
total: the total number of machines.

User methods

List an organization's users

GET /api/2/organization/<organization_id>/persons

Query Parameters

offset: zero-based offset from which to start listing people. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 person objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of person objects.
total: the total number of people.

List an organization's guests

GET /api/2/organization/<organization_id>/guests

Query Parameters

offset: zero-based offset from which to start listing guests. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 guest objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of guest objects.
total: the total number of guests.

Group methods

List an organization's groups

GET /api/2/organization/<organization_id>/groups

Query Parameters

offset: zero-based offset from which to start listing groups. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 group objects...
    ],
    "total": 12
}

offset: the offset given in the method call or zero.
results: a list of group objects.
total: the total number of groups.

Authentication source methods

List an organization's authentication sources

GET /api/2/organization/<organization_id>/auth_sources

Query Parameters

offset: zero-based offset from which to start listing child organizations. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 authentication source objects...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of authentication source objects.
total: the total number of authentication sources.

List an organization's authentication source nicknames

GET /api/2/organization/<organization_id>/auth_sources/nicknames
GET /api/2/organization/<slug>/auth_sources/nicknames
GET /api/2/organization/<hostname>/auth_sources/nicknames

Response

Organization has auth sources configured, but none have nicknames

HTTP status code: 200
Response body:
{
    "results": []
}

Organization has auth sources configured with nicknames

HTTP status code: 200
Response body:
{
    "results": [
        ...a list of auth source nickname strings...
    ]
}

Errors

Organization does not exist or has no auth sources configured

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Activity methods

List recent activity for an organization

GET /api/2/organization/<organization_id>/activity

Query Parameters

offset: zero-based offset from which to start listing activity records. Defaults to 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 activity objects in reverse chronological order...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of activity objects in reverse chronological order.
total: the total number of activity records available for the organization.

Metrics methods

Get usage for an organization

GET /api/2/organization/<organization_id>/metrics/usage

Response

HTTP status code: 200
Response body:
{
    ...an organization usage object...
}

Errors

The following errors may occur for any organization method and are not explicitly mentioned in the method descriptions.

Authenticated user does not have access to view or modify the organization

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Organization does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Person

Person object

A person object represents an leitzcloud user account.

Attributes

type string

"person"
id integer

The unique identifier for the person
email string

The person's email address
username string

The person's username
company_id integer

The identifier of the company to which the person belongs
first_name string

The person's first name
last_name string

The person's last name
display_name string

The person's name formatted for display
root_id integer

The identifier of the person's sync root
roots list

A list of root objects to which the person is subscribed
space_quota integer

The person's space quota in bytes
space_quota_formatted string

The person's space quota in human friendly formatting
space_usage integer

The amount of space used by the person in bytes
space_usage_formatted string

The amount of space used by the person in human friendly formatting
can_share boolean

Whether the person's company policy allows them to create shares
company_policy object

The expanded company policy object

Example

{
    "can_share": true,
    "company_policy": {
        ...
    },
    "display_name": "First Last",
    "email": "user@example.com",
    "first_name": "First",
    "id": 1,
    "last_name": "Last",
    "root_id": 1,
    "roots": [
        ...
    ],
    "space_quota": 10000,
    "space_quota_formatted": "10k",
    "space_usage": 100,
    "space_usage_formatted": "100b",
    "type": "person",
    "username": ""
}

Person methods

Get a person

The person method returns information about the authenticated user or a user with a given ID or email address.

GET /api/2/person
GET /api/2/person/<person_id>
GET /api/2/person/<email>

Response

HTTP status code: 200
Response body:
{
    ...a person object...
}

Create a person

POST /api/2/person/create

POST Fields

company_id:
email:
first_name:
last_name:
password:
generate_password:
pw_expires:
webdav:
space_quota:
mobile_phone:
site_admin:
system_admin:
create_root:
dept_shares:
group_ids:
quota_50:
quota_80:
quota_85:
quota_90:
quota_95:
quota_100:
send_welcome_email:

Response

Returns the created person.

HTTP status code: 200
Response body:
{
    ...a person object...
}

Update a person

POST /api/2/person/<person_id>/update

Response

Returns the updated person.

HTTP status code: 200
Response body:
{
    ...a person object...
}

Errors

Password unchanged

This error indicates that password was included in the request, but is the same as the existing password.

HTTP status code: 400
Response body:
{
    "error": "password_unchanged"
}

Delete a person

POST /api/2/person/<person_id>/delete

POST Fields

remove_server_files:
remove_user_files: whether to delete the user's account root.
remove_dept_files: whether to delete files owned by the user in team shares.

Response

HTTP status code: 200

Create an account sync root

Create a sync root for an account if one does not already exist.

POST /api/2/person/<person_id>/roots/create

POST Fields

Optional

webdav: whether to enable webdav access. Default "false".

Response

Returns the created root.

HTTP status code: 200
Response body:
{
    ...a root object...
}

List files and folders shared by a person

GET /api/2/person/<person_id>/sharelinks

Query Parameters

sort_by: the field on which to sort: "created", "expires", "creator_name", "times_viewed", or "times_downloaded". Default "created".
sort_order: the sort direction: "asc" or "desc". Default "asc".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size file and folder share link objects...
    ],
    "total": 42
}

page: the page given in the method call or 1.
page_size: the page_size given in the method call or 20.
max_page: the total number of result pages.
results: a list of share link objects.
total: the total number of result records available.

List files and folders shared with a person

GET /api/2/person/<person_id>/sharelinks/received

Query Parameters

sort_by: the field on which to sort: "created", "expires", "creator_name", "times_viewed", or "times_downloaded". Default "created".
sort_order: the sort direction: "asc" or "desc". Default "asc".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size file and folder share link objects...
    ],
    "total": 42
}

page: the page given in the method call or 1.
page_size: the page_size given in the method call or 20.
max_page: the total number of result pages.
results: a list of share link objects.
total: the total number of result records available.

List recent activity for a person

GET /api/2/person/<person_id>/activity

Query Parameters

offset: zero-based offset from which to start listing activity records. Default 0.

Response

HTTP status code: 200
Response body:
{
    "offset": 0,
    "results": [
        ...up to 100 activity objects in reverse chronological order...
    ],
    "total": 42
}

offset: the offset given in the method call or zero.
results: a list of activity objects in reverse chronological order.
total: the total number of activity records available for the person.

Enable two-step authentication

POST /api/2/person/two_step/enable

Fields

Required

password: the authenticated user's password.
mode: the two-step authentication mode to use: "authenticator", "email", or "sms".

Optional

auth_code: the two-step authentication code. When excluded, triggers two-step authentication code delivery when mode is "sms" or "email". Required to complete enabling of two-step authentication.
mobile_phone: when mode=sms, updates the authenticated user's mobile phone number.

Response

Step 1: auth_code is not present

HTTP status code: 200
Response body:
{
  "backup_key": "GZTEQRKMGIYDS4JU",
  "key": "GM4EUUKOKNMHEZS2OZ2UE43YNVYG4OL2",
  "uri": "otpauth://totp/foo@example.com?secret=GM4EUUKOKNMHEZS2OZ2UE43YNVYG4OL2"
}

Step 2: auth_code provided

HTTP status code: 200

Errors

Password or authentication code are not valid

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Disable two-step authentication

POST /api/2/person/two_step/disable

Fields

Required

password: the authenticated user's password.

Optional

auth_code: the two-step authentication code. When excluded, triggers two-step authentication code delivery when configured two-step mode is "sms" or "email". Required to complete disabling of two-step authentication.

Response

HTTP status code: 200

Errors

Password or authentication code are not valid

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Two-step authentication recovery

POST /api/2/person/two_step/recovery

Fields

Required

email: the email address of the user initiating two-step recovery.
backup_key: the user's two-step recovery backup key.

Response

HTTP status code: 200

Errors

Backup key can not be verified

HTTP status code: 401
Response body:
{
    "error": "access_denied"
}

Errors

The following errors may occur for any person method and are not explicitly mentioned in the method descriptions.

Authenticated user does not have access to view or modify the person

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Person does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Guest

Guest object

A guest represents a restricted account with limited access to shared files.

Attributes

type string

"guest"
id integer

The unique identifier for the guest
company_id integer

The identifier of the company to which the guest belongs
creator_id integer

The identifier of the person who created the guest
email string

The guest's email address
first_name string

The guest's first name
last_name string

The guest's last name
active boolean

Whether the guest account is active
created string

The date/time in UTC the guest was created in the format YYYY-MM-DDTHH:MM:SS

Example

{
    "active": true,
    "company_id": 1,
    "created": "2015-01-01T01:02:03",
    "creator_id": 1,
    "email": "guest@example.com",
    "first_name": "First",
    "id": 1,
    "last_name": "Last",
    "type": "guest"
}

Guest methods

Get a guest

Retrieve a guest by ID or email address.

GET /api/2/guest/<guest_id>
GET /api/2/guest/<email>

Response

HTTP status code: 200
Response body:
{
    ...a guest object...
}

Create a guest

POST /api/2/guest/create

POST Fields

Required

company_id: the identifier of the company in which to create the guest.
first_name: the guest's first name.
last_name: the guest's last name.
email: the guest's email address.
password: the guest's password. Required if generate_password is "false".
generate_password: whether to automatically generate a password. Required if password is not provided. Default "false".

Optional

send_welcome_email: send a welcome email to the guest? Default "false".
pw_expires: number of hours until the password expires. Valid options are empty (never), "6", "12", and "24". Default never.

Response

Returns the created guest.

HTTP status code: 200
Response body:
{
    ...a guest object...
}

Update a guest

POST /api/2/guest/<guest_id>/update

POST Fields

Optional

first_name: the guest's first name.
last_name: the guest's last name.
email: the guest's email address.
password: the guest's password.
pw_expires: number of hours until the password expires. Valid options are empty (never), "6", "12", and "24". Default never.

Response

Returns the updated guest.

HTTP status code: 200
Response body:
{
    ...a guest object...
}

Delete a guest

POST /api/2/guest/<guest_id>/delete

Response

HTTP status code: 200

Get files and folders shared with a guest

GET /api/2/guest/<guest_id>/shares

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...file share link objects...
    ]
}

Convert a guest to a standard account

POST /api/2/guest/<guest_id>/convert

Response

Returns the created account.

HTTP status code: 200
Response body:
{
    ...a person object...
}

Errors

User limit exceeded

Occurs when converting the guest account would exceed the organization's account limit.

HTTP status code: 409
Response body:
{
    "error": "user_limit_exceeded",
    "error_description": "User limit has been reached."
}

Group

Group object

A group represents a collection of users and other groups.

Attributes

type string

"group"
id integer

The unique identifier for the group
company_id integer

The unique identifier for the group's organization
name string

The group name
created string

The date/time in UTC the group was created in in the format YYYY-MM-DDTHH:MM:SS
active boolean

Whether the group is active

Example

{
    "active": true,
    "company_id": 2,
    "created": "2016-03-30T05:57:23",
    "id": 1,
    "name": "Example Group",
    "type": "group"
}

Group methods

Create a group

POST /api/2/group/create

POST Fields

Required

name: the group name.
company_id: the organization ID in which to create the group.

Optional

members: a JSON list of integer person IDs.
member_groups: a JSON list of integer group IDs.

Response

Returns the created group.

HTTP status code: 200
Response body:
{
    ...a group object...
}

Get a group

GET /api/2/group/<group_id>

Response

HTTP status code: 200
Response body:
{
    ...a group object...
}

Update a group

POST /api/2/group/<group_id>/update

POST Fields

Optional

name: the group name.

Response

Returns the updated group.

HTTP status code: 200
Response body:
{
    ...a group object...
}

List group members

GET /api/2/group/<group_id>/members

Query Parameters

include_from_group: include individual subscribers from subscribed groups? Defaults to "false".

Response

HTTP status code: 200
Response body:
{
    "member_groups": [
        2
    ],
    "member_groups_from_group": [
        3
    ],
    "members": [
        2,
        3
    ],
    "members_from_group": [
        1
    ]
}

member_groups: a list of group IDs that are direct members of the group.
member_groups_from_group: a list of group IDs that are inherited members of the group. Only present if include_from_group is "true".
members: a list of person IDs that are direct members of the group.
members_from_group: a list of person IDs that are inherited members of the group. Only present if include_from_group is "true".

Update group members

POST /api/2/group/<group_id>/members/update

POST Fields

Optional

members: a JSON list of integer person IDs.
member_groups: a JSON list of integer group IDs.
remove_files: remove files from unsubscribed agents? Default "false".

Response

HTTP status code: 200

Delete a group

POST /api/2/group/<group_id>/delete

POST Fields

Optional

remove_files: remove files from subscribed agents? Default "false".

Response

HTTP status code: 200

Machine

Machine object

A machine represents a device used to connect to leitzcloud, such as a computer, phone, or tablet.

Attributes

type string

"machine"
id integer

The unique identifier for the machine
dns_name string

A descriptive name for the machine, such as the host name or device manufacturer and model
nickname string
last_login string

The date/time in UTC the machine last logged in in the format YYYY-MM-DDTHH:MM:SS. Used by the desktop agent.
guid string

A globally unique identifier assigned to the machine
created string

The date/time in UTC the machine was created in in the format YYYY-MM-DDTHH:MM:SS
os_type string

The machine's system type, such as "win", "osx", "android" or "ios"
os_version string

The machine's system version, such as "5.1.0"
agent_version string

The agent version installed on the machine. Used by the desktop agent.
locked boolean
bandwidth_throttle integer
throttle_exception_days string
throttle_exception_dow list of integers
throttle_exception_start string
throttle_exception_end string
throttle_exception_throttle integer
throttled boolean

Whether bandwidth throttling is enabled for the machine
machine_type string

The machine type
last_disconnect string

The date/time in UTC the machine last disconnected in in the format YYYY-MM-DDTHH:MM:SS. Used by the desktop agent.
health_report_period_minutes integer

Average number of minutes between machine health reports or null if using the agent default health report period.
health_report_period_minutes_min integer

Minimum number of minutes between machine health reports or null if using the agent default health report period.
health_report_period_minutes_max integer

Maximum number of minutes between machine health reports or null if using the agent default health report period.
manual_collisions boolean

Example

{
    "agent_version": null,
    "bandwidth_throttle": null,
    "created": "2015-01-01T01:02:03",
    "dns_name": "Google Nexus 6",
    "guid": "794f7f67-3bd6-407c-9274-be735b880143",
    "health_report_period_minutes": null,
    "id": 1,
    "last_disconnect": null,
    "last_login": null,
    "locked": false,
    "machine_type": "mobile",
    "manual_collisions": true,
    "nickname": null,
    "os_type": "android",
    "os_version": "5.1.0",
    "throttle_exception_days": null,
    "throttle_exception_dow": null,
    "throttle_exception_end": null,
    "throttle_exception_start": null,
    "throttle_exception_throttle": null,
    "throttled": false,
    "type": "machine"
}

Machine mapping object

A machine mapping represents a path on a file server enabled machine mapped to a root.

Attributes

type string

"machine_mapping"
id integer

The unique identifier for the mapping
machine_id integer

The identifier of the file server enabled machine to which the root is mapped
name string

The mapping name
path string

The path on the file server enabled machine to which the root is mapped
person_id integer

The identifier of the account if the mapped root is an account root
root_id integer

The identifier of the mapped root
share boolean

Whether the mapped root is a share

Example

{
    "id": 1234,
    "machine_id": 1,
    "name": "Example Share",
    "path": "C:\Example1",
    "person_id": null,
    "root_id": 2,
    "share": true,
    "type": "machine_mapping"
}

Backup object

A backup represents a backup root mapped to a path on a file server enabled machine.

Attributes

type string

"backup"
id integer

The unique identifier for the backup
machine_id integer

The identifier of the file server enabled machine to which the root is mapped
path string

The path on the file server enabled machine from which files are backed up

Example

{
    "id": 1234,
    "machine_id": 1,
    "path": "C:\\Example",
    "type": "backup"
}

Machine methods

Get a machine

GET /api/2/machine/<machine_id>

Response

HTTP status code: 200
Response body:
{
    ...a machine object...
}

Get a machine's status

GET /api/2/machine/<machine_id>/status

Response

HTTP status code: 200
Response body:
{
    "results": {
        "subscriptions": [
            {
                "excl_files": 1,
                "rsub_id": 1234,
                "synced": true,
                "synced_folder": "C:\\Example"
            }
        ],
        "synced": true,
        "transfers": []
    }
}

File Server Enablement methods

Enable file server on a machine

POST /api/2/machine/<machine_id>/server/enable

Response

HTTP status code: 200

Disable file server on a machine

POST /api/2/machine/<machine_id>/server/disable

Response

HTTP status code: 200

List files on a file server enabled machine

POST /api/2/machine/<machine_id>/ls

POST Fields

Optional

path: the directory path to list, or none to list drives. Default none.
username: the username if path is a network path and requires authentication. Default none.
password: the password if path is a network path and requires authentication. Default none.

Response

HTTP status code: 200
Response body:
{
    "results": [
        "Example1",
        "Example2"
    ]
}

List mapped paths on a file server enabled machine

GET /api/2/machine/<machine_id>/mappings

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...machine_mapping objects...
    ]
}

Map a path on a file server enabled machine to a root

POST /api/2/machine/<machine_id>/mappings/create

POST Fields

Required

root_id: the identifier of the root to be mapped.
path: the path on the file server enabled machine to which the root will be mapped.

Optional

username: the username if path is a network path and requires authentication. Default none.
password: the password if path is a network path and requires authentication. Default none.

Response

Returns the created mapping.

HTTP status code: 200
Response body:
{
    ...a machine_mapping object...
}

Get a machine mapping

GET /api/2/machine/<machine_id>/mapping/<mapping_id>

Response

HTTP status code: 200
Response body:
{
    ...a machine_mapping object...
}

Delete a machine mapping

POST /api/2/machine/<machine_id>/mapping/<mapping_id>/delete

Response

HTTP status code: 200

Backup methods

List backups

GET /api/2/machine/<machine_id>/backups

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...backup objects...
    ]
}

Create a backup

POST /api/2/machine/<machine_id>/backups/create

POST Fields

Required

path: the path on the file server enabled machine to which the root will be mapped.

Optional

username: the username if path is a network path and requires authentication. Default none.
password: the password if path is a network path and requires authentication. Default none.

Response

Returns the created backup.

HTTP status code: 200
Response body:
{
    ...a backup object...
}

Get a backup

GET /api/2/machine/<machine_id>/backup/<root_id>

Response

HTTP status code: 200
Response body:
{
    ...a backup object...
}

Restore a backup

POST /api/2/machine/<machine_id>/backup/<root_id>/restore

POST Fields

Required

path: the path on the file server enabled machine to which the backup will be restored.

Optional

to_machine_id: the id of the machine to which the backup will be restored. Defaults to restore to the machine the backup is on.

Response

Returns the updated backup object.

HTTP status code: 200
Response body:
{
    ...a backup object...
}

Delete a backup

POST /api/2/machine/<machine_id>/backup/<root_id>/delete

Response

HTTP status code: 200

Errors

The following errors may occur for any machine method and are not explicitly mentioned in the method descriptions.

Authenticated user does not have access to view or modify the machine

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Machine does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Activity

Activity object

An activity represents a logged action including details of the acting entity and the affected entity.

Attributes

type string

"activity"
id integer

The unique identifier for the activity
actor_type string

The entity type triggering the activity
actor_text string

The description of the entity triggering the activity
actor_company_id integer
actor_machine_id integer
actor_person_id integer
actor_guest_id integer
action_text string

Additional description of the action taken
acted_on_type string

The entity type being acted upon
acted_on_text string

The description of the entity type being acted upon
acted_on_company_id integer
acted_on_machine_id integer
acted_on_person_id integer
acted_on_guest_id integer
acted_on_root_id integer
acted_on_group_id integer
data_text string

The description of the action taken
activity_type_id integer

The identifier of the activity type for this activity
created string

The date/time in UTC the activity occurred in the format YYYY-MM-DDTHH:MM:SS
processed boolean

Example

{
    "acted_on_company_id": 1,
    "acted_on_group_id": null,
    "acted_on_guest_id": null,
    "acted_on_machine_id": null,
    "acted_on_person_id": null,
    "acted_on_root_id": null,
    "acted_on_text": "Example Company",
    "acted_on_type": "site",
    "action_text": null,
    "activity_type_id": 8,
    "actor_company_id": null,
    "actor_guest_id": null,
    "actor_machine_id": null,
    "actor_person_id": 1,
    "actor_text": "First Last",
    "actor_type": "person",
    "created": "2015-01-01T01:02:03",
    "data_text": "increased from 4.00G to 100.00G",
    "id": 123,
    "processed": true,
    "type": "activity"
}

Activity type object

Attributes

type string

"activity_type"
id integer

The unique identifier for the activity type
activity string

The activity description
machine_scope boolean

Whether the activity is performed within the scope of a machine
user_scope boolean

Whether the activity is performed within the scope of a user
system_scope boolean

Whether the activity is performed at the system level

Example

{
    "activity": "added organization",
    "id": 3,
    "machine_scope": false,
    "system_scope": false,
    "type": "activity_type",
    "user_scope": false
}

Activity methods

Get a list of activity types

GET /api/2/activity/types

Response

HTTP status code: 200
Response body:
{
    "results": [
        ...a list of activity objects...
    ]
}

Get an activity record

GET /api/2/activity/<activity_id>

Response

HTTP status code: 200
Response body:
{
    ...an activity object...
}

Create an activity record

POST /api/2/activity/create

Response

Returns the created activity record.

HTTP status code: 200
Response body:
{
    ...an activity object...
}

Errors

The following errors may occur for any activity method and are not explicitly mentioned in the method descriptions.

Authenticated user does not have access to view or modify the activity or activity type

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Activity or activity type does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Authentication source

Authentication source object

An authentication source represents a directory server from which users may be imported.

Attributes

type string

"auth_source"
id integer

The unique identifier for the authentication source
host string

The hostname of the directory server
domain string

The domain name on the directory server to use for importing users
login string

The user name used to access the directory server
port integer

The port number of the directory server
protocol integer
ssl boolean

Whether the directory server uses SSL/TLS
machine_id integer
nickname string

A public nickname for the authentication source, displayed to visitors on the login page

Example

{
    "domain": "example.com",
    "host": "localhost",
    "id": 1,
    "login": "example",
    "machine_id": null,
    "nickname": "example",
    "port": null,
    "protocol": null,
    "ssl": false,
    "type": "auth_source"
}

Share link

File share link object

Attributes

type string

"file_sharelink"
id integer

The unique identifier of the file share link
hash string

The "public" hash used to create the unique share link URL
file object

The shared file object
root_id integer

The identifier of the root containing the shared file
creator_id integer

The identifier of the share link creator
creator_name string

The name of the share link creator for display
created string

The date/time in UTC the share link was created in the format YYYY-MM-DDTHH:MM:SS
expires string

The date the share expires in the format YYYY-MM-DD or null if it has no expiration
login_required boolean

Whether the share link is public (false) or only accessible to authenticated subscribers (true)
download_limit integer

The maximum number of times the share link may be downloaded or null if there is no limit
download_notify boolean

Whether the share link creator is notified when the shared file is downloaded
anon_edit boolean

Whether files may be edited via the public share link URL (i.e. by anonymous users)
subscribers array

An array of share link subscriber objects. Note: this may not always contain the full list of subscribers, depending on the context of the request. For example, when getting files and folders shared with a guest only the subscriber details for the guest being requested will be returned.
times_downloaded integer

Total number of times the shared file has been downloaded. May vary based on the context of the request.
times_viewed integer

Total number of times the share link has been accessed. May vary based on the context of the request.
url string

The share link URL.

Example

{
    "anon_edit": false,
    "created": "2019-03-27T10:42:34",
    "creator_name": "Jane Doe",
    "creator_id": 1,
    "download_limit": 1000,
    "download_notify": true,
    "expires": "2019-04-28",
    "file": {
        ...a file object...
    },
    "hash": "10d2d8d4e15e91",
    "id": 1,
    "login_required": true,
    "root_id": 1,
    "subscribers": [
        ...share link subscriber objects...
    ],
    "times_downloaded": 0,
    "times_viewed": 0,
    "type": "file_sharelink",
    "url": "http://example.com/shares/file/10d2d8d4e15e91/"
}

Folder share link object

Attributes

type string

"folder_sharelink"
id integer

The unique identifier of the folder share link
hash string

The "public" hash used to create the unique share link URL
folder object

The shared folder object
root_id integer

The identifier of the root containing the shared folder
creator_id integer

The identifier of the share link creator
creator_name string

The name of the share link creator for display
created string

The date/time in UTC the share link was created in the format YYYY-MM-DDTHH:MM:SS
expires string

The date the share link expires in the format YYYY-MM-DD or null if it has no expiration
login_required boolean

Whether the share link is public (false) or only accessible to authenticated subscribers (true)
download_limit integer

The maximum number of times the share link may be downloaded or null if there is no limit
download_notify boolean

Whether the share link creator is notified when the shared folder is downloaded via the share link
upload_notify boolean

Whether the share link creator is notified when a file is uploaded to the shared folder via the share link
anon_edit boolean

Whether files may be edited via the public share link URL (i.e. by anonymous users)
subscribers array

An array of share link subscriber objects. Note: this may not always contain the full list of subscribers, depending on the context of the request. For example, when getting files and folders shared with a guest only the subscriber details for the guest being requested will be returned.
times_downloaded integer

Total number of times the shared folder has been downloaded. May vary based on the context of the request.
times_viewed integer

Total number of times the share link has been accessed. May vary based on the context of the request.
url string

The share link URL.

Example

{
    "anon_edit": false,
    "created": "2019-03-27T11:54:34",
    "creator_name": "Jane Doe",
    "creator_id": 1,
    "download_limit": null,
    "download_notify": false,
    "expires": null,
    "folder": {
        ...a folder object...
    },
    "hash": "10d2d8d4e15e91",
    "id": 1,
    "login_required": false,
    "root_id": 1,
    "subscribers": [
        ...share link subscriber objects...
    ],
    "times_downloaded": 0,
    "times_viewed": 0,
    "type": "folder_sharelink",
    "upload_notify": false,
    "url": "http://example.com/shares/folder/10d2d8d4e15e91/"
}

Share link subscriber object

Attributes

type string

"sharelink_subscriber"
id integer

The unique identifier of the share link subscription
hash string

The subscriber's share hash used to create their unique share link URL
read_access boolean

Whether the subscriber has read access.
write_access boolean

Whether the subscriber has write access.
delete_access boolean

Whether the subscriber has delete access.
subscriber_type string

The subscriber type associated with the subscription: person, guest, group, or email
subscriber object or string

An object containing additional subscriber metadata when subscriber_type is person, guest, or group. The subscriber's email address as a string when subscriber_type is email.
times_downloaded integer

Number of times the shared file or folder was downloaded using the subscriber's share hash.
times_viewed integer

Number of times the share link was accessed using the subscriber's share hash.
url string

The subscriber's share link URL.

Example

{
    "delete_access": false,
    "hash": "d2d8d4e119105e",
    "id": 1,
    "read_access": true,
    "subscriber": {
        "email": "example@example.com",
        "id": 1,
        "name": "Jane Doe"
    },
    "subscriber_type": "person",
    "times_downloaded": 0,
    "times_viewed": 0,
    "type": "sharelink_subscriber",
    "write_access": false,
    "url": "http://example.com/shares/file/d2d8d4e119105e/"
}

Share link methods

Get a share link by ID

GET /api/2/sharelinks/<sharelink_id>

Query Parameters

include_subscribers: whether to include share link subscribers in the response. Only the share creator or an administrator may view all subscribers for a share link; otherwise, the response will include only the requester's subscriber object. "true" or "false". Default "false".

Response

HTTP status code: 200
Response body:
{
    ...a file share link object or a folder share link object...
}

Get a share link by hash

GET /api/2/sharelinks/<hash>

Query Parameters

include_subscribers: whether to include share link subscribers in the response. Only the share creator or an administrator may view all subscribers for a share link; otherwise, the response will include only the requester's subscriber object. "true" or "false". Default "false".

Response

HTTP status code: 200
Response body:
{
    ...a file share link object or a folder share link object...
}

Update a share link

PUT /api/2/sharelinks/<sharelink_id>

Fields

Optional

login_required: whether the share link is public (false) or only accessible to authenticated subscribers (true). "true" or "false".
expires: the date the share link expires in the format YYYY-MM-DD.
download_limit: the maximum number of times the share link may be downloaded.
download_notify: whether the share link creator is notified when the shared file or folder is downloaded via the share link. "true" or "false".
upload_notify: whether the share link creator is notified when a file is uploaded to the shared folder via the share link. "true" or "false". Only applicable for folder share links.
anon_edit: whether files may be edited via the public share link URL (i.e. by anonymous users). "true" or "false".

Response

HTTP status code: 200
Response body:
{
    ...a file share link object or a folder share link object...
}

Delete a share link

DELETE /api/2/sharelinks/<sharelink_id>

Response

HTTP status code: 200

Add a share link subscriber by email

POST /api/2/sharelinks/<sharelink_id>/subscribers

Fields

Required

email: the subscriber's email address.

Optional

write_access: whether the subscriber has access to upload and edit files in a shared folder. "true" or "false". Default "false".
delete_access: whether the subscriber has access to delete files from a shared folder. Only applicable for folder share links. "true" or "false". Default "false".
notify: whether to notify the subscriber of the new subscription. "true" or "false". Default "true".
message: an additional message to include in the subscription notification when notify is "true". Default none.

Response

HTTP status code: 200
Response body:
{
    ...a share link subscriber object...
}

Add a share link subscriber by type and ID

POST /api/2/sharelinks/<sharelink_id>/subscribers

Fields

Required

subscriber_type: the subscriber's type ("person", "guest", or "group").
subscriber_id: the subscriber's ID (e.g. the group ID when subscriber_type is "group").

Optional

write_access: whether the subscriber has access to upload and edit files in a shared folder. "true" or "false". Default "false".
delete_access: whether the subscriber has access to delete files from a shared folder. Only applicable for folder share links. "true" or "false". Default "false".
notify: whether to notify the subscriber of the new subscription. "true" or "false". Default "true".
message: an additional message to include in the subscription notification when notify is "true". Default none.

Response

HTTP status code: 200
Response body:
{
    ...a share link subscriber object...
}

Update a share link subscriber

PUT /api/2/sharelinks/<sharelink_id>/subscribers/<subscriber_id>

Fields

Optional

write_access: whether the subscriber has access to upload and edit files in a shared folder. "true" or "false". Default "false".
delete_access: whether the subscriber has access to delete files from a shared folder. Only applicable for folder share links. "true" or "false". Default "false".
notify: whether to notify the subscriber of the new subscription. "true" or "false". Default "false".
message: an additional message to include in the subscription notification when notify is "true". Default none.

Response

HTTP status code: 200
Response body:
{
    ...a share link subscriber object...
}

Delete a share link subscriber

DELETE /api/2/sharelinks/<sharelink_id>/subscribers/<subscriber_id>

Response

HTTP status code: 200

Shared content methods

Get share link folder metadata

GET /api/2/sharelinks/<sharelink_id>/files
GET /api/2/sharelinks/<hash>/files
GET /api/2/sharelinks/<sharelink_id>/files/folder/<folder_id>
GET /api/2/sharelinks/<hash>/files/folder/<folder_id>

Query Parameters

include_ancestors: whether to include the folder's ancestors in the response. "true" or "false". Default "false".
include_children: whether to include the folder's children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
hash: the hash value returned by the last call to this method. Only used when include_children is "true".

Response

HTTP status code: 200
Response body:
{
    ...a folder object...
}

children is a list of file and folder metadata objects within the folder. It is only present when include_children is "true".

Get metadata for a shared folder's children

GET /api/2/sharelinks/<sharelink_id>/files/children
GET /api/2/sharelinks/<hash>/files/children
GET /api/2/sharelinks/<sharelink_id>/files/folder/<folder_id>/children
GET /api/2/sharelinks/<hash>/files/folder/<folder_id>/children

Returns metadata for the immediate children of a shared folder with options for sorting and pagination.

Query Parameters

include_deleted: whether to include deleted children in the response. "true" or "false". Default "true".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".
include_permissions: whether to include the user's file and folder permissions in the response. "true" or "false". Default "false".
sort_by: the field on which to sort: "name", "modified", or "size". Default "name".
sort_order: the sort direction: "asc" or "desc". Default "asc".
page: the results page to return: 1 to max_page. Default 1.
page_size: the number of results to return per page: 1 to 100. Default 20.

Response

HTTP status code: 200
Response body:
{
    "page": 1,
    "page_size": 20,
    "max_page": 3,
    "results": [
        ...up to page_size file and folder objects...
    ],
    "total": 42
}

Get share link file metadata

GET /api/2/sharelinks/<sharelink_id>/files/<file_id>
GET /api/2/sharelinks/<hash>/files/<file_id>

Query Parameters

include_ancestors: whether to include the file's ancestors in the response. "true" or "false". Default "false".
include_lock_info: whether to include lock information in the response. "true" or "false". Default "true".

Response

HTTP status code: 200
Response body:
{
    ...a file object...
}

Download all share link contents

GET /api/2/sharelinks/<sharelink_id>/download
GET /api/2/sharelinks/<sharelink_id>/view

These endpoints are used to download the complete contents of a share link, the file itself for a shared file or the zipped contents of a shared folder.

Whether the file is downloaded via the download endpoint or view endpoint determines the Content-Disposition in the response -- attachment or inline, respectively. A shared folder does not support view and will respond with a 404.

Query Parameters

Optional

file_ids: a comma-separated list of file IDs to include in the download. Must be direct children of the resource specified in the request. Only available for the download endpoint.
folder_ids: a comma-separated list of folder IDs to include in the download. Must be direct children of the resource specified in the request. Only available for the download endpoint.

If either file_ids or folder_ids is present, the download will include only the items specified.

Response

HTTP status code: 200
Response body:
<binary file data>

Download a file within a shared folder

GET /api/2/sharelinks/<sharelink_id>/files/<file_id>/download
GET /api/2/sharelinks/<sharelink_id>/files/<file_id>/view
GET /api/2/sharelinks/<hash>/files/<file_id>/download
GET /api/2/sharelinks/<hash>/files/<file_id>/view

These endpoints are used to download a specific file within a shared folder.

Whether the file is downloaded via the download endpoint or view endpoint determines the Content-Disposition in the response -- attachment or inline, respectively.

Response

HTTP status code: 200
Response body:
<binary file data>

Download a subfolder of a shared folder

GET /api/2/sharelinks/<sharelink_id>/files/folder/<folder_id>/download
GET /api/2/sharelinks/<hash>/files/folder/<folder_id>/download

These endpoints are used to download a specific folder within a shared folder as a zip file.

Query Parameters

Optional

file_ids: a comma-separated list of file IDs to include in the download. Must be direct children of the resource specified in the request. Only available for the download endpoint.
folder_ids: a comma-separated list of folder IDs to include in the download. Must be direct children of the resource specified in the request. Only available for the download endpoint.

If either file_ids or folder_ids is present, the download will include only the items specified.

Response

HTTP status code: 200
Response body:
<binary file data>

Create a subfolder in a shared folder

POST /api/2/sharelinks/<sharelink_id>/files/create_folder
POST /api/2/sharelinks/<hash>/files/create_folder
POST /api/2/sharelinks/<sharelink_id>/files/folder/<folder_id>/create_folder
POST /api/2/sharelinks/<hash>/files/folder/<folder_id>/create_folder

Fields

name: the new folder name. Required.

Response

HTTP status code: 200
Response body:
{
    ...folder metadata...
}

Errors

Invalid folder name

HTTP status code: 400
Response body:
{
    "error": "invalid_name"
}

Folder name is too long

HTTP status code: 400
Response body:
{
    "error": "name_too_long"
}

A folder with the same name already exists

HTTP status code: 409
Response body:
{
    "error": "name_conflict"
}

Errors

The following errors may occur for any share link method and are not explicitly mentioned in the method descriptions.

Authenticated user does not have access to view or modify the share link

HTTP status code: 403
Response body:
{
    "error": "forbidden"
}

Share link does not exist

HTTP status code: 404
Response body:
{
    "error": "not_found"
}

Change Log

Date	Changes
2021-03-02	Added health_report_period_minutes_min and health_report_period_minutes_max to the machine object
2020-04-10	Added file_ids and folder_ids parameters to the following endpoints: Download a folder Download all share link contents Download a subfolder of a shared folder Added endpoints to create a subfolder in a shared folder
2020-03-26	Added "view" endpoints to download a file and download a revision Added share link content endpoints Added share link content download endpoints: Download all share link contents Download a file within a shared folder Download a subfolder of a shared folder
2020-03-18	Added method to get metadata for a root's children Added method to get metadata for a folder's children Added method to get metadata for a shared folder's children
2020-03-06	Added methods to get share link file and folder metadata Added "include_ancestors" support to all file/folder metadata methods Added "name" attribute to file and folder objects
2020-03-05	Added method to list an organization's authentication source nicknames Added "nickname" attribute to authentication source object
2019-12-05	Added method to list revisions for a file Added method to get metadata for a single revision Added method to download a file revision
2019-11-18	Added methods to enable and disable two-step authentication
2019-05-24	Added change log section Added two-step authentication recovery method
2019-05-10	Added methods to request and confirm password reset tokens
2019-04-07	Added share link collection, including share link and share subscriber objects and associated methods Added methods to get share links sent and received by a user
2019-03-27	Added method to get usage metrics for an organization
2019-01-28	Added method to convert a guest to a standard account