API v2 Reference

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.

Endpoint

https:///api/2

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

Responses

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.

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 Anchor'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 version method.

Authentication

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.

General

Version

The version method returns the exact API version available in the format ... 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

  • hash string

    A hash of the root metadata used for results caching

Example
{ "children": [ ...child files and folders... ], "hash": "", "id": 1, "is_locked": false, "name": "Example Files", "path": "/", "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

  • 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

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

    "folder"

  • id integer

    The unique identifier of the folder

  • root_id integer

    The identifier of the root containing the folder

  • 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

  • hash string

    A hash of the folder metadata used for results caching

Example
{ "children": [ ...child files and folders... ], "hash": "", "id": 1, "is_deleted": false, "is_locked": false, "path": "/path/to/name", "root_id": 1, "type": "folder" }

File share object

Attributes
  • type string

    "file_share"

  • id integer

    The unique identifier of the file share

  • file_id integer

    The identifier of the shared file, or null if it's a shared folder

  • folder_id integer

    The identifier of the shared folder, or null if it's a shared file

  • root_id integer

    The identifier of the root containing the file or folder

  • hash string

    The share hash used to create the unique share link

  • expires string

    The date/time in UTC the share expires in the format YYYY-MM-DDTHH:MM:SS or null if it has no expiration

  • read_access boolean

    Whether the user has read access. May not be present if there is no user context.

  • write_access boolean

    Whether the user has write access. May not be present if there is no user context.

  • delete_access boolean

    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///download
Response
HTTP status code: 200 Response body:

Share a file

POST /api/2/files///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".

Rename a file

POST /api/2/files///rename
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///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///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///unlock
Response
HTTP status code: 200

Delete a file

POST /api/2/files///delete
Response
HTTP status code: 200

Folder method

Get folder metadata

GET /api/2/files//folder/
Query Parameters
  • include_children: "true" or "false". Default "true".
  • include_deleted: "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".

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

Upload a file to a folder

POST /api/2/files//folder//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" }
A file with the same name already exists
HTTP status code: 409 Response body: { "error": "name_conflict" }

Create a subfolder

POST /api/2/files//folder//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//folder//download
Response
HTTP status code: 200 Response body:

Share a folder

POST /api/2/files//folder//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".

Rename a folder

POST /api/2/files//folder//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//folder//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//folder//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//folder//unlock
Response
HTTP status code: 200

Delete a folder

POST /api/2/files//folder//delete
Response
HTTP status code: 200

Root methods

Get root metadata

GET /api/2/files/
Query Parameters
  • include_children: "true" or "false". Default "true".
  • include_deleted: "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 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

Upload a file to a root

POST /api/2/files//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" }
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//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//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//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//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//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."" }

Person

Person object

A person object represents an Anchor 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/ GET /api/2/person/
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//update
Response

Returns the updated person.

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

Delete a person

POST /api/2/person//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//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 recent activity for a person

GET /api/2/person//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.

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" }

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

  • num_users_minimum integer

    The minimum 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 verification

  • 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

  • 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