The vBoxxCloud 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 vBoxxCloud API must be performed over HTTPS. Non-HTTPS requests will be rejected.
vBoxxCloud 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 vBoxxCloud 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 vBoxxCloud 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 list of the authenticated user's permissions on the root.
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": "/",
"permissions": [
"FILE_VIEW",
"FILE_READ",
"FILE_WRITE"
],
"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
A list of the authenticated user's permissions on the file.
{
"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",
"permissions": [
"FILE_VIEW",
"FILE_READ",
"FILE_WRITE"
],
"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 list of the authenticated user's permissions on the folder.
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",
"permissions": [
"FILE_VIEW",
"FILE_READ",
"FILE_WRITE"
],
"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
}
"root_space_usage"
Number of deleted files
Number of deleted revisions
Space usage of deleted files in bytes
Space usage of deleted files in human friendly formatting
Total number of files
Space usage of non-deleted files in bytes
Space usage of non-deleted files in human friendly formatting
Total space usage in bytes
Total space usage in human friendly formatting
Number of revisions
Space usage of revisions in bytes
Space usage of revisions in human friendly formatting
The total number of roots included in the usage metrics
{
"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"
}
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: 400
Response body:
{
"error": "invalid_extension"
}
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: 400
Response body:
{
"error": "invalid_extension"
}
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: 400
Response body:
{
"error": "invalid_extension"
}
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.""
}
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
The maximum space allowed to be used by the organization in human friendly formatting
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
{
"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,
"num_users_minimum": 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"
A root space usage object of backup usage metrics
A root space usage object of team share usage metrics
A root space usage object of total usage metrics for all roots
A root space usage object of user root usage metrics
{
"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"
Total number of accounts
Number of admin accounts
Number of groups
Number of guests
Number of machines
Number of organizations
{
"accounts": 11,
"admin_accounts": 5,
"groups": 8,
"guests": 4,
"machines": 6,
"organizations": 7,
"type": "organization_usage_counts"
}
GET /api/2/organization/<organization_id> GET /api/2/organization/<license_key>
HTTP status code: 200
Response body:
{
...an organization object...
}
POST /api/2/organization/<organization_id>/organizations/create
Returns the created organization.
HTTP status code: 200
Response body:
{
...an organization object...
}
POST /api/2/organization/<organization_id>/update
Returns the updated organization.
HTTP status code: 200
Response body:
{
...an organization object...
}
POST /api/2/organization/<organization_id>/disable
POST /api/2/organization/<organization_id>/enable
POST /api/2/organization/<organization_id>/delete
POST /api/2/organization/<organization_id>/policy/update
Returns the updated organization.
HTTP status code: 200
Response body:
{
...an organization object...
}
GET /api/2/organization/<organization_id>/organizations
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 organization objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/roots
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 root objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/root/<root_id>
HTTP status code: 200
Response body:
{
...a root object...
}
GET /api/2/organization/<organization_id>/shares
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 root objects...
],
"total": 42
}
POST /api/2/organization/<organization_id>/shares/create
Returns the created share.
HTTP status code: 200
Response body:
{
...a root object...
}
GET /api/2/organization/<organization_id>/share/<root_id>
HTTP status code: 200
Response body:
{
...a root object...
}
POST /api/2/organization/<organization_id>/share/<root_id>/update
Returns the updated share.
HTTP status code: 200
Response body:
{
...a root object...
}
GET /api/2/organization/<organization_id>/share/<root_id>/subscribers
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"]]
}
POST /api/2/organization/<organization_id>/share/<root_id>/subscribers/update
HTTP status code: 200
POST /api/2/organization/<organization_id>/share/<root_id>/delete
HTTP status code: 200
GET /api/2/organization/<organization_id>/machines
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 machine objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/persons
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 person objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/guests
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 guest objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/groups
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 group objects...
],
"total": 12
}
GET /api/2/organization/<organization_id>/auth_sources
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 authentication source objects...
],
"total": 42
}
GET /api/2/organization/<organization_id>/activity
HTTP status code: 200
Response body:
{
"offset": 0,
"results": [
...up to 100 activity objects in reverse chronological order...
],
"total": 42
}
GET /api/2/organization/<organization_id>/metrics/usage
HTTP status code: 200
Response body:
{
...an organization usage object...
}
The following errors may occur for any organization 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"
}
A person object represents an vBoxxCloud 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"
}
A guest represents a restricted account with limited access to shared files.
"guest"
The unique identifier for the guest
The identifier of the company to which the guest belongs
The identifier of the person who created the guest
The guest's email address
The guest's first name
The guest's last name
Whether the guest account is active
The date/time in UTC the guest was created in the format YYYY-MM-DDTHH:MM:SS
{
"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"
}
Retrieve a guest by ID or email address.
GET /api/2/guest/<guest_id> GET /api/2/guest/<email>
HTTP status code: 200
Response body:
{
...a guest object...
}
POST /api/2/guest/create
Returns the created guest.
HTTP status code: 200
Response body:
{
...a guest object...
}
POST /api/2/guest/<guest_id>/update
Returns the updated guest.
HTTP status code: 200
Response body:
{
...a guest object...
}
POST /api/2/guest/<guest_id>/delete
HTTP status code: 200
GET /api/2/guest/<guest_id>/shares
HTTP status code: 200
Response body:
{
"results": [
...file share objects...
]
}
POST /api/2/guest/<guest_id>/convert
Returns the created account.
HTTP status code: 200
Response body:
{
...a person object...
}
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."
}
A group represents a collection of users and other groups.
"group"
The unique identifier for the group
The unique identifier for the group's organization
The group name
The date/time in UTC the group was created in in the format YYYY-MM-DDTHH:MM:SS
Whether the group is active
{
"active": true,
"company_id": 2,
"created": "2016-03-30T05:57:23",
"id": 1,
"name": "Example Group",
"type": "group"
}
POST /api/2/group/create
Returns the created group.
HTTP status code: 200
Response body:
{
...a group object...
}
GET /api/2/group/<group_id>
HTTP status code: 200
Response body:
{
...a group object...
}
POST /api/2/group/<group_id>/update
Returns the updated group.
HTTP status code: 200
Response body:
{
...a group object...
}
GET /api/2/group/<group_id>/members
HTTP status code: 200
Response body:
{
"member_groups": [
2
],
"member_groups_from_group": [
3
],
"members": [
2,
3
],
"members_from_group": [
1
]
}
include_from_group is "true".include_from_group is "true".POST /api/2/group/<group_id>/members/update
HTTP status code: 200
POST /api/2/group/<group_id>/delete
HTTP status code: 200
A machine represents a device used to connect to vBoxxCloud, such as a computer, phone, or tablet.
"machine"
The unique identifier for the machine
A descriptive name for the machine, such as the host name or device manufacturer and model
The date/time in UTC the machine last logged in in the format YYYY-MM-DDTHH:MM:SS. Used by the desktop agent.
A globally unique identifier assigned to the machine
The date/time in UTC the machine was created in in the format YYYY-MM-DDTHH:MM:SS
The machine's system type, such as "win", "osx", "android", "ios", or "winphone"
The machine's system version, such as "5.1.0"
The agent version installed on the machine. Used by the desktop agent.
Whether bandwidth throttling is enabled for the machine
The machine type
The date/time in UTC the machine last disconnected in in the format YYYY-MM-DDTHH:MM:SS. Used by the desktop agent.
{
"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"
}
A machine mapping represents a path on a file server enabled machine mapped to a root.
"machine_mapping"
The unique identifier for the mapping
The identifier of the file server enabled machine to which the root is mapped
The mapping name
The path on the file server enabled machine to which the root is mapped
The identifier of the account if the mapped root is an account root
The identifier of the mapped root
Whether the mapped root is a share
{
"id": 1234,
"machine_id": 1,
"name": "Example Share",
"path": "C:\Example1",
"person_id": null,
"root_id": 2,
"share": true,
"type": "machine_mapping"
}
A backup represents a backup root mapped to a path on a file server enabled machine.
"backup"
The unique identifier for the backup
The identifier of the file server enabled machine to which the root is mapped
The path on the file server enabled machine from which files are backed up
{
"id": 1234,
"machine_id": 1,
"path": "C:\\Example",
"type": "backup"
}
GET /api/2/machine/<machine_id>
HTTP status code: 200
Response body:
{
...a machine object...
}
GET /api/2/machine/<machine_id>/status
HTTP status code: 200
Response body:
{
"results": {
"subscriptions": [
{
"excl_files": 1,
"rsub_id": 1234,
"synced": true,
"synced_folder": "C:\\Example"
}
],
"synced": true,
"transfers": []
}
}
POST /api/2/machine/<machine_id>/server/enable
HTTP status code: 200
POST /api/2/machine/<machine_id>/server/disable
HTTP status code: 200
POST /api/2/machine/<machine_id>/ls
HTTP status code: 200
Response body:
{
"results": [
"Example1",
"Example2"
]
}
GET /api/2/machine/<machine_id>/mappings
HTTP status code: 200
Response body:
{
"results": [
...machine_mapping objects...
]
}
POST /api/2/machine/<machine_id>/mappings/create
Returns the created mapping.
HTTP status code: 200
Response body:
{
...a machine_mapping object...
}
GET /api/2/machine/<machine_id>/mapping/<mapping_id>
HTTP status code: 200
Response body:
{
...a machine_mapping object...
}
POST /api/2/machine/<machine_id>/mapping/<mapping_id>/delete
HTTP status code: 200
GET /api/2/machine/<machine_id>/backups
HTTP status code: 200
Response body:
{
"results": [
...backup objects...
]
}
POST /api/2/machine/<machine_id>/backups/create
Returns the created backup.
HTTP status code: 200
Response body:
{
...a backup object...
}
GET /api/2/machine/<machine_id>/backup/<root_id>
HTTP status code: 200
Response body:
{
...a backup object...
}
POST /api/2/machine/<machine_id>/backup/<root_id>/restore
Returns the updated backup object.
HTTP status code: 200
Response body:
{
...a backup object...
}
POST /api/2/machine/<machine_id>/backup/<root_id>/delete
HTTP status code: 200
The following errors may occur for any machine 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 activity represents a logged action including details of the acting entity and the affected entity.
"activity"
The unique identifier for the activity
The entity type triggering the activity
The description of the entity triggering the activity
Additional description of the action taken
The entity type being acted upon
The description of the entity type being acted upon
The description of the action taken
The identifier of the activity type for this activity
The date/time in UTC the activity occurred in the format YYYY-MM-DDTHH:MM:SS
{
"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"
The unique identifier for the activity type
The activity description
Whether the activity is performed within the scope of a machine
Whether the activity is performed within the scope of a user
Whether the activity is performed at the system level
{
"activity": "added organization",
"id": 3,
"machine_scope": false,
"system_scope": false,
"type": "activity_type",
"user_scope": false
}
GET /api/2/activity/types
HTTP status code: 200
Response body:
{
"results": [
...a list of activity objects...
]
}
GET /api/2/activity/<activity_id>
HTTP status code: 200
Response body:
{
...an activity object...
}
POST /api/2/activity/create
Returns the created activity record.
HTTP status code: 200
Response body:
{
...an activity object...
}
The following errors may occur for any activity 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 authentication source represents a directory server from which users may be imported.
"auth_source"
The unique identifier for the authentication source
The hostname of the directory server
The domain name on the directory server to use for importing users
The user name used to access the directory server
The port number of the directory server
Whether the directory server uses SSL/TLS
{
"domain": "example.com",
"host": "localhost",
"id": 1,
"login": "example",
"machine_id": null,
"port": null,
"protocol": null,
"ssl": false,
"type": "auth_source"
}
"file_sharelink"
The unique identifier of the file share link
The "public" hash used to create the unique share link URL
The shared file object
The identifier of the root containing the shared file
The identifier of the share link creator
The name of the share link creator for display
The date/time in UTC the share link was created in the format YYYY-MM-DDTHH:MM:SS
The date the share expires in the format YYYY-MM-DD or null if it has no expiration
Whether the share link is public (false) or only accessible to authenticated subscribers (true)
The maximum number of times the share link may be downloaded or null if there is no limit
Whether the share link creator is notified when the shared file is downloaded
Whether files may be edited via the public share link URL (i.e. by anonymous users)
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.
Total number of times the shared file has been downloaded. May vary based on the context of the request.
Total number of times the share link has been accessed. May vary based on the context of the request.
The share link URL.
{
"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_sharelink"
The unique identifier of the folder share link
The "public" hash used to create the unique share link URL
The shared folder object
The identifier of the root containing the shared folder
The identifier of the share link creator
The name of the share link creator for display
The date/time in UTC the share link was created in the format YYYY-MM-DDTHH:MM:SS
The date the share link expires in the format YYYY-MM-DD or null if it has no expiration
Whether the share link is public (false) or only accessible to authenticated subscribers (true)
The maximum number of times the share link may be downloaded or null if there is no limit
Whether the share link creator is notified when the shared folder is downloaded via the share link
Whether the share link creator is notified when a file is uploaded to the shared folder via the share link
Whether files may be edited via the public share link URL (i.e. by anonymous users)
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.
Total number of times the shared folder has been downloaded. May vary based on the context of the request.
Total number of times the share link has been accessed. May vary based on the context of the request.
The share link URL.
{
"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/"
}
"sharelink_subscriber"
The unique identifier of the share link subscription
The subscriber's share hash used to create their unique share link URL
Whether the subscriber has read access.
Whether the subscriber has write access.
Whether the subscriber has delete access.
The subscriber type associated with the subscription: person, guest, group, or email
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.
Number of times the shared file or folder was downloaded using the subscriber's share hash.
Number of times the share link was accessed using the subscriber's share hash.
The subscriber's share link URL.
{
"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/"
}
GET /api/2/sharelinks/<sharelink_id>
HTTP status code: 200
Response body:
{
...a file share link object or a folder share link object...
}
GET /api/2/sharelinks/<hash>
HTTP status code: 200
Response body:
{
...a file share link object or a folder share link object...
}
PUT /api/2/sharelinks/<sharelink_id>
HTTP status code: 200
Response body:
{
...a file share link object or a folder share link object...
}
DELETE /api/2/sharelinks/<sharelink_id>
HTTP status code: 200
POST /api/2/sharelinks/<sharelink_id>/subscribers
HTTP status code: 200
Response body:
{
...a share link subscriber object...
}
POST /api/2/sharelinks/<sharelink_id>/subscribers
HTTP status code: 200
Response body:
{
...a share link subscriber object...
}
PUT /api/2/sharelinks/<sharelink_id>/subscribers/<subscriber_id>
HTTP status code: 200
Response body:
{
...a share link subscriber object...
}
DELETE /api/2/sharelinks/<sharelink_id>/subscribers/<subscriber_id>
HTTP status code: 200
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>
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".
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.
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 /api/2/sharelinks/<sharelink_id>/files/<file_id> GET /api/2/sharelinks/<hash>/files/<file_id>
HTTP status code: 200
Response body:
{
...a file object...
}
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.
download endpoint.download endpoint.If either file_ids or folder_ids is present, the download will include only the items specified.
HTTP status code: 200 Response body: <binary file data>
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.
HTTP status code: 200 Response body: <binary file data>
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.
download endpoint.download endpoint.If either file_ids or folder_ids is present, the download will include only the items specified.
HTTP status code: 200 Response body: <binary file data>
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
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"
}
The following errors may occur for any share link 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"
}