The Anchor 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.
https://<hostname:port>/api/2
All requests to the Anchor API must be performed over HTTPS. Non-HTTPS requests will be rejected.
Anchor 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 Anchor server.
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.
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:
HTTP status code: 400
Response body:
{
"error": "invalid_request"
}
HTTP status code: 401
Response body:
{
"error": "access_denied"
}
HTTP status code: 403
Response body:
{
"error": "forbidden"
}
HTTP status code: 404
Response body:
{
"error": "not_found"
}
HTTP status code: 500
Response body:
{
"error": "unknown"
}
HTTP status code: 400
Response body:
{
"error": "insecure_transport",
"error_description": "Requests MUST utilize https."
}
HTTP status code: 400
Response body:
{
"error": "invalid_request",
"error_description": "Missing required parameter: <param>"
}
HTTP status code: 400
Response body:
{
"error": "invalid_request",
"error_description": "Invalid value for parameter: <param>"
}
HTTP status code: 400
Response body:
{
"error": "invalid_date_format",
"error_description": "Invalid date format. The expected format is: YYYY-MM-DD"
}
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.
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.
Unless otherwise noted, all Anchor 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.
The version method returns the exact API version available in the format <major>.<minor>.<revision>.
Authentication is not required.
GET /api/2/version
HTTP status code: 200
Response body:
{
"version": "2.0.9"
}
"root"
The unique identifier of the root
The name of the root
"/"
Whether the root is locked
The type of the root: "sync", "share", or "backup"
The total size of the root in bytes
The total size of the root in human friendly formatting
A hash of the root metadata used for results caching
{
"children": [
...child files and folders...
],
"hash": "<hash>",
"id": 1,
"is_locked": false,
"name": "Example Files",
"path": "/",
"root_type": "sync",
"space_used": 10000,
"space_used_formatted": "10k",
"type": "root"
}
"file"
The unique identifier of the file
The unique revision identifier of the file
The identifier of the root containing the file
The absolute path of the file within the root
Whether the file is deleted
The date/time in UTC the file was created in the format YYYY-MM-DDTHH:MM:SS
The date/time in UTC the file was last modified in the format YYYY-MM-DDTHH:MM:SS
The size of the file in bytes
The size of the file in human friendly formatting
Whether the file is locked
{
"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"
The unique identifier of the folder
The identifier of the root containing the folder
The absolute path of the folder within the root
Whether the folder is deleted
Whether the folder is locked
A hash of the folder metadata used for results caching
{
"children": [
...child files and folders...
],
"hash": "<hash>",
"id": 1,
"is_deleted": false,
"is_locked": false,
"path": "/path/to/name",
"root_id": 1,
"type": "folder"
}
"file_share"
The unique identifier of the file share
The identifier of the shared file, or null if it's a shared folder
The identifier of the shared folder, or null if it's a shared file
The identifier of the root containing the file or folder
The share hash used to create the unique share link
The date/time in UTC the share expires in the format YYYY-MM-DDTHH:MM:SS or null if it has no expiration
Whether the user has read access. May not be present if there is no user context.
Whether the user has write access. May not be present if there is no user context.
Whether the user has delete access. May not be present if there is no user context.
{
"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
}
GET /api/2/files/<root_id>/<file_id>
HTTP status code: 200
Response body:
{
...a file object...
}
GET /api/2/files/<root_id>/<file_id>/download
HTTP status code: 200 Response body: <binary file data>
POST /api/2/files/<root_id>/<file_id>/share
POST /api/2/files/<root_id>/<file_id>/rename
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/<file_id>/move
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/<file_id>/lock
HTTP status code: 200
POST /api/2/files/<root_id>/<file_id>/unlock
HTTP status code: 200
POST /api/2/files/<root_id>/<file_id>/delete
HTTP status code: 200
GET /api/2/files/<root_id>/folder/<folder_id>
include_children
is "true".
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".
POST /api/2/files/<root_id>/folder/<folder_id>/upload
HTTP status code: 200
Response body:
{
...file metadata...
}
HTTP status code: 400
Response body:
{
"error": "no_file_received",
"error_description": "Missing required file: file"
}
HTTP status code: 409
Response body:
{
"error": "policy_error"
}
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/folder/<folder_id>/create_folder
HTTP status code: 200
Response body:
{
...folder metadata...
}
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 400
Response body:
{
"error": "name_too_long"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
GET /api/2/files/<root_id>/folder/<folder_id>/download
HTTP status code: 200 Response body: <binary zip file data>
POST /api/2/files/<root_id>/folder/<folder_id>/share
POST /api/2/files/<root_id>/folder/<folder_id>/rename
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 400
Response body:
{
"error": "name_too_long"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/folder/<folder_id>/move
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/folder/<folder_id>/lock
HTTP status code: 200
POST /api/2/files/<root_id>/folder/<folder_id>/unlock
HTTP status code: 200
POST /api/2/files/<root_id>/folder/<folder_id>/delete
HTTP status code: 200
GET /api/2/files/<root_id>
include_children
is "true".
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".
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".
HTTP status code: 304
POST /api/2/files/<root_id>/upload
HTTP status code: 200
Response body:
{
...file metadata...
}
HTTP status code: 400
Response body:
{
"error": "no_file_received",
"error_description": "Missing required file: file"
}
HTTP status code: 409
Response body:
{
"error": "policy_error"
}
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
POST /api/2/files/<root_id>/create_folder
HTTP status code: 200
Response body:
{
...folder metadata...
}
HTTP status code: 400
Response body:
{
"error": "invalid_name"
}
HTTP status code: 400
Response body:
{
"error": "name_too_long"
}
HTTP status code: 409
Response body:
{
"error": "name_conflict"
}
GET /api/2/files/<root_id>/search
HTTP status code: 200
Response body:
{
"results": [
...file and folder metadata...
]
}
GET /api/2/files/<root_id>/modified_since
HTTP status code: 200
Response body:
{
"results": [
...file metadata...
]
}
POST /api/2/files/<root_id>/lock
HTTP status code: 200
POST /api/2/files/<root_id>/unlock
HTTP status code: 200
The following errors may occur for any file system method and are not explicity mentioned in the method descriptions.
HTTP status code: 403
Response body:
{
"error": "forbidden"
}
HTTP status code: 404
Response body:
{
"error": "not_found"
}
HTTP status code: 409
Response body:
{
"error": "resource_locked"
}
HTTP status code: 410
Response body:
{
"error": "root_deleted",
"error_description": "Root was previously deleted."
}
HTTP status code: 503
Response body:
{
"error": "temporarily_unavailable",
"error_description": "Service is temporarily unavailable.""
}
A person object represents an Anchor user account.
"person"
The unique identifier for the person
The person's email address
The person's username
The identifier of the company to which the person belongs
The person's first name
The person's last name
The person's name formatted for display
The identifier of the person's sync root
A list of root objects to which the person is subscribed
The person's space quota in bytes
The person's space quota in human friendly formatting
The amount of space used by the person in bytes
The amount of space used by the person in human friendly formatting
Whether the person's company policy allows them to create shares
The expanded company policy object
{
"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": ""
}
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>
HTTP status code: 200
Response body:
{
...a person object...
}
POST /api/2/person/create
Returns the created person.
HTTP status code: 200
Response body:
{
...a person object...
}
POST /api/2/person/<person_id>/update
Returns the updated person.
HTTP status code: 200
Response body:
{
...a person object...
}
POST /api/2/person/<person_id>/delete
HTTP status code: 200
Create a sync root for an account if one does not already exist.
POST /api/2/person/<person_id>/roots/create
Returns the created root.
HTTP status code: 200
Response body:
{
...a root object...
}
GET /api/2/person/<person_id>/activity
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 activity objects in reverse chronological order...
],
"total": 42
}
The following errors may occur for any person method and are not explicitly mentioned in the method descriptions.
HTTP status code: 403
Response body:
{
"error": "forbidden"
}
HTTP status code: 404
Response body:
{
"error": "not_found"
}
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.
"organization"
The unique identifier for the organization
The unique identifier of the parent organization
The organization name
The URL friendly organization name
A description of the organization
The organization's contact email address
The hostname your organization's agents will use to connect
The date/time in UTC the organization was created in the format YYYY-MM-DDTHH:MM:SS
Whether bandwidth throttling is enabled for the organization
Whether the organization is active
The date/time in UTC the organization's trial period expires in the format YYYY-MM-DDTHH:MM:SS
Whether privacy mode is enabled for the organization
{
"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"
The identifier of the organization to which the policy belongs
Whether administrators can browse files
Whether administrators can browser remote files
Whether administrators can create users
Whether backups are enabled
Whether custom branding is enabled
A comma-delimited list of file extensions not allowed to be uploaded
A comma-delimited list of file extensions
The maximum uploaded file size in XX
The maximum number of child organizations allowed
The maximum number of users allowed
The minimum number of users allowed
Whether PSA integration is enabled
Whether deleted files are automatically purged
The frequency at which deleted files are automatically purged
Whether mobile app users are required to use a PIN lock
Whether users are required to enable two step verification
Whether file shares are required to be private
The maximum space allowed to be used by the organization
Whether file revisions are automatically trimmed
Whether users are allowed to create backup roots
Whether users are allowed to share files
Whether users are allowed to lock files
Whether users are allowed to purge deleted files
Whether users are allowed to trim file revisions
Whether WebDAV access is enabled