Leitz-Cloud API2
API V2 REFERENCE DOCUMENT
API v2 Reference
Root object ............................................................................................................................................... 8
File object ............................................................................................................................................... 10
Folder object .......................................................................................................................................... 13
File share object ..................................................................................................................................... 15
File methods .......................................................................................................................................... 17
Folder method ....................................................................................................................................... 20
Root methods ........................................................................................................................................ 27
Errors ..................................................................................................................................................... 32
Person object ......................................................................................................................................... 34
Person methods ..................................................................................................................................... 37
Errors ..................................................................................................................................................... 40
Organization object ................................................................................................................................ 41
Policy object ........................................................................................................................................... 45
Organization methods ........................................................................................................................... 50
Root methods ........................................................................................................................................ 54
Machine methods .................................................................................................................................. 61
User methods ......................................................................................................................................... 61
Authentication source methods ............................................................................................................ 63
Activity methods .................................................................................................................................... 64
Errors ..................................................................................................................................................... 64
Machine object ...................................................................................................................................... 66
Machine mapping object ....................................................................................................................... 69
Backup object......................................................................................................................................... 71
Machine methods .................................................................................................................................. 72
File Server Enablement methods ........................................................................................................... 73
Backup methods .................................................................................................................................... 76
Errors ..................................................................................................................................................... 78
Guest object ........................................................................................................................................... 80
Guest methods ....................................................................................................................................... 82
Activity object ........................................................................................................................................ 85
Activity type object ................................................................................................................................ 87
Activity methods .................................................................................................................................... 89
Errors ..................................................................................................................................................... 90
API v2 Reference
The 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:
All requests to the Leitz Cloud API must be performed over HTTPS. Non-HTTPS requests will be rejected.
Responses
Leitz Cloud 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 Leitz Cloud 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 Leitz Cloud'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: "
}
Request contains an invalid parameter value
HTTP status code: 400 Response body:
{
"error": "invalid_request",
"error_description": "Invalid value for parameter: "
}
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"
}
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 versionmethod.
Authentication
Unless otherwise noted, all Leitz Cloud 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
Version
The versionmethod returns the exact API version available in the format
GET /api/2/version
Response
HTTP status code: 200 Response body:
{
"version": "2.0.9"
}
File system
Root object
Attributes
typestring
"root"
idinteger
The unique identifier of the root
namestring
The name of the root
pathstring
"/"
is_lockedboolean
Whether the root is locked
root_typestring
The type of the root: "sync", "share", or "backup"
space_usedinteger
The total size of the root in bytes
space_used_formattedstring
The total size of the root in human friendly formatting
childrenlist
A list of child files and folders
hashstring
A hash of the root metadata used for results caching
Example
{
"children": [
...child files and folders...
],
"hash": "
"is_locked": false, "name": "Example Files", "path": "/",
"root_type": "sync", "space_used": 10000, "space_used_formatted": "10k", "type": "root"
}
File object
Attributes
typestring
"file"
idinteger
The unique identifier of the file
revision_idinteger
The unique revision identifier of the file
root_idinteger
The identifier of the root containing the file
pathstring
The absolute path of the file within the root
is_deletedboolean
Whether the file is deleted
createdstring
The date/time in UTC the file was created in the format YYYY-MM- DDTHH:MM:SS
modifiedstring
The date/time in UTC the file was last modified in the format YYYY-MM- DDTHH:MM:SS
sizeinteger
The size of the file in bytes
size_formattedstring
The size of the file in human friendly formatting
is_lockedboolean
Whether the file is locked
Example
{
"created": "2015-01-01T01:02:03", "id": 1,
"is_deleted": false, "is_locked": false,
"modified": "2015-01-01T02:03:04",
"path": "/path/to/file.ext", "revision_id": 1,
"root_id": 1,
"size": 12205, "size_formatted": "11.92k", "type": "file"
}
Folder object
Attributes
typestring
"folder"
idinteger
The unique identifier of the folder
root_idinteger
The identifier of the root containing the folder
pathstring
The absolute path of the folder within the root
is_deletedboolean
Whether the folder is deleted
is_lockedboolean
Whether the folder is locked
childrenlist
A list of child files and folders
hashstring
A hash of the folder metadata used for results caching
Example
{
"children": [
...child files and folders...
],
"hash": "
"is_deleted": false, "is_locked": false, "path": "/path/to/name", "root_id": 1,
"type": "folder"
}
File share object
Attributes
typestring
"file_share"
idinteger
The unique identifier of the file share
file_idinteger
The identifier of the shared file, or null if it's a shared folder
folder_idinteger
The identifier of the shared folder, or null if it's a shared file
root_idinteger
The identifier of the root containing the file or folder
hashstring
The share hash used to create the unique share link
expiresstring
The date/time in UTC the share expires in the format YYYY-MM- DDTHH:MM:SS or null if it has no expiration
read_accessboolean
Whether the user has read access. May not be present if there is no user context.
write_accessboolean
Whether the user has write access. May not be present if there is no user context.
delete_accessboolean
Whether the user has delete access. May not be present if there is no user context.
Example
{
"creator_id": 2, "delete_access": false, "expires": null, "file_id": 4,
"folder_id": null,
"hash": "06d0d4833ea65c", "id": 7,
"read_access": true, "root_id": 3,
"type": "share", "write_access": false }
File methods
Get file metadata
GET /api/2/files/
Response
HTTP status code: 200 Response body:
{
...a file object...
}
Download a file
GET /api/2/files/
Response
HTTP status code: 200 Response body:
Share a file
POST /api/2/files/
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".
Rename a file
POST /api/2/files/
POST Fields
name: the new file name. Required.
Errors
Invalid file name
HTTP status code: 400 Response body:
{
"error": "invalid_name"
}
A file with the same name already exists
HTTP status code: 409 Response body:
{
"error": "name_conflict"
}
Move a file
POST /api/2/files/
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/
POST Fields
duration: the number of minutes after which the lock will be automatically released.
Response
HTTP status code: 200