Getting Started

  • Join our Oxygen developer community.
  • Register for an app key to begin developing your own app.

Sample Application

A REST API sample script written in Python is available to get started quickly.

This script allows you to log in with your Oxygen user and list the spaces your user is subscribed to.

Simply download the file and replace the necessary values in the STEP 0: CUSTOMIZE INPUT PARAMETERS section. You'll need an API_KEY and API_SECRET from your developer program membership and also a valid Oxygen user account for the OXYGEN_USER_ID and OXYGEN_PASSWORD values. Once these values are set, you can run the script using Python 2.7.x. Please contact support if you have any questions or if you'd like to join our developer program.

There is also an O2shell sample application (also Python) available for reference.

API Basics

Each Oxygen REST API call is an HTTPS request that may use either GET or POST methods with the exception of login which must use the POST method. Each request also requires a valid authentication header. You will need both your assigned app key and app secret to generate the authentication header.

The following table is an example:

Header KeyDescription

X-App-KeyRegistered app key.
X-TimestampCurrent time in seconds since epoch.
X-SignatureHMAC-SHA1 signature: uses your registered app secret.
X-Session*Session ID. (Use /login or /validate_auth or /redeem_sso_token to establish a valid session.)

Note: X-Session is the authentication token received after successful login.

Error Handling

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call and will be JSON-formatted.

Standard ErrorsDescription

101Invalid signature.
103Invalid timestamp.
104Invalid session.
105Invalid app key.
107Invalid parameter(s).
108System busy.

You will find additional error codes under the REST API methods listed below.


Authentication

/rest/account/login

DESCRIPTION

Obtains a session for making other API calls. This call must use the POST method.

POST  /rest/account/login?id=your@email.com&password=password123

PARAMETERS

id: your Oxygen ID
password: your password

RETURNS

An authenticated session ID to be used as the value of the "X-Session" header in subsequent API calls.

SAMPLE JSON RESPONSE

{ "session": "b272aad843d93a31fac72a0d597b7d6481b34e1c" }

ERROR CODES

401: Invalid login id or password.


/rest/account/request_auth

DESCRIPTION

Request a login page URL.

GET  /rest/account/request_auth?success_url=http%3A%2F%2Fmyapp.com%2F

PARAMETERS

success_url: Page to redirect to after a successful login

RETURNS

Login URL and an unauthenticated token.

SAMPLE JSON RESPONSE

{ "token": "402881863e9ccaf4013e9cd2843f0006", "url": "https://wgw.oxygencloud.com/webauth/Login.jsp?tokenId=40288..." }

ERROR CODES

107: Invalid success URL.


/rest/account/validate_auth

DESCRIPTION

Obtains a session from a token after the token has been authenticated via the login page.

GET  /rest/account/validate_auth?token=402881863e9ccaf4013e9cd2843f0006

PARAMETERS

token: The token that would be authenticated after a sucessful login

RETURNS

An authenticated session ID to be used as the value of the "X-Session" header in subsequent API calls.

SAMPLE JSON RESPONSE

{ "session": "b272aad843d93a31fac72a0d597b7d6481b34e1c" }

ERROR CODES

401: The token has not been authenticated.


/rest/account/request_sso_token

DESCRIPTION

Request a single-use, time-limited authenticated token for the purpose of SSO.

GET  /rest/account/request_sso_token

PARAMETERS

None

RETURNS

An authenticated SSO token.

SAMPLE JSON RESPONSE

{ "token": "402881863e9ccaf4013e9cd2843f0006" }

ERROR CODES

104: Invalid session.


/rest/account/redeem_sso_token

DESCRIPTION

Obtains a session from an authenticated SSO token.

GET  /rest/account/redeem_sso_token?token=402881863e9ccaf4013e9cd2843f0006

PARAMETERS

token: The authenticated SSO token

RETURNS

An authenticated session ID to be used as the value of the "X-Session" header in subsequent API calls.

SAMPLE JSON RESPONSE

{ "session": "b272aad843d93a31fac72a0d597b7d6481b34e1c" }

ERROR CODES

401: The token is invalid or the token has expired.


/rest/account/logout

DESCRIPTION

Logout session.

GET  /rest/account/logout

PARAMETERS  
RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

104: Invalid or expired session.


View Files

/rest/files/list

DESCRIPTION

Lists files and folders at a path.

GET  /rest/files/list?path=/a/b&spaceOid=52ba11ab-9883-4388

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path to the folder (path '/' is for listing the root Space contents)

RETURNS

Current list of files and folders in specified location (If the path is root and the spaceOid is blank, subscribed spaces will also be listed).

SAMPLE JSON RESPONSE

{ "data": {
  "folders": [
    {"name": "Shared Space", "type": "space", "oid" : "a8d931b2-e29d-4bbe-93f0-8f140a82dd10-51c9f2ab"},
    {"name": "Project Folder", "type": "folder", "seq": 121}
  ], "files": [
    {"name": "proposal.doc", "seq": 122, "contentId": "63b6b8f2-5270-4ad7-8a41-087a08fb5595", "modified": 1360360729, "size": 21365}
]} }

ERROR CODES

202: Path not found.
222: Path is not in a valid format, or path points to a file.
341: Space not found.
406: You do not have permission to view the space.


/rest/files/get_info

DESCRIPTION

Get info about a file or folder at a path.

GET  /rest/files/get_info?path=/a/b&spaceOid=52ba11ab-9883-4388

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path to the file or folder

RETURNS

Detailed information about the path, where "type" can be "file" or "folder" or "space".

SAMPLE JSON RESPONSE

{ "type": "file", contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "created": 1373341002, "modified": 1373566588, "size": 100, "lastModifiedBy": "John Doe" }

ERROR CODES

202: Path not found.
222: Path is not in a valid format, or path points to a file.
341: Space not found.
406: You do not have permission to view the space.


/rest/files/download

DESCRIPTION

Gets a download link for a file.

GET  /rest/files/download?path=/a/b/proposal.doc

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path to the file

RETURNS

A unique URL to download the file.

SAMPLE JSON RESPONSE

{ "url": "https://custom-storage.company.com/storagegateway/download?id=2edc9868..." }

ERROR CODES

202: Path not found.
203: Path is not a file.
222: Path is not in a valid format.
341: Space not found.
406: You do not have permission to view the space.
601: File was not found in the storage.


Modify Files

/rest/files/upload

DESCRIPTION

Upload step 1 of 2: Gets an direct upload link for the file. In order for the service to determine the correct direct upload link, if the upload destination is in a specific space, you must provide either the spaceOid or the path parameter.

GET  /rest/files/upload?path=/a/b/questionnaire.doc&size=53821

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: (optional) expected absolute path (destination) of the file
size: size of the file in bytes

RETURNS

A unique URL to upload the file.

SAMPLE JSON RESPONSE

{ "uploadId": "a36d1ff7...", "url": "https://custom-storage.company.com/storagegateway/upload?id=a36d1ff7..." }

ERROR CODES

204: Parent folder not found.
214: Invalid file size.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.


/rest/files/commit_upload

DESCRIPTION

Upload step 2 of 2: Commits the file upload.

GET  /rest/files/commit_upload?uploadId=a36d1ff7...&path=/a/b/questionnaire.doc&hash=78a922ef...&modified=1360382729

PARAMETERS

uploadId: value of uploadId returned from the upload call
spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path (destination) of the file
hash: sha1 hash of the file content
modified: last modified timestamp in epoch time

RETURNS

New sequence number and content information as a result of this operation.

SAMPLE JSON RESPONSE

{ "seq": 2048, "contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "modified": 1373566588, "size": 100 }

ERROR CODES

204: Parent folder not found.
214: Invalid file size.
215: Invalid modified timestamp.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.
540: Not enough available storage.
601: File was not uploaded (e.g. /upload was not called, or uploadId not found, or upload session has expired).


/rest/files/add_file

DESCRIPTION

Equivalent to /confirm_upload except that it supports verifying the sequence number of the parent.

GET  /rest/files/add_file?uploadId=a36d1ff7...&path=/a/b/questionnaire.doc&hash=78a922ef...&modified=1360382729&seq=2123

PARAMETERS

uploadId: value of uploadId returned from the upload call
spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path (destination) of the file
hash: encoded hash of the file
modified: last modified timestamp in epoch time
seq: (optional) expected sequence number of parent folder

RETURNS

New sequence number and content information as a result of this operation.

SAMPLE JSON RESPONSE

{ "seq": 2049, "contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "modified": 1373566588, "size": 100 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
204: Parent folder not found.
214: Invalid file size.
215: Invalid modified timestamp.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.
540: Not enough available storage.
601: File was not uploaded (e.g. /upload was not called, or uploadId not found, or upload session has expired).


/rest/files/update_file

DESCRIPTION

Equivalent to /confirm_upload except that it supports verifying the file already exists and that the expected sequence number matches.

GET  /rest/files/update_file?uploadId=a36d1ff7...&path=/a/b/questionnaire.doc&hash=78a922ef...&modified=1360382729&seq=2123

PARAMETERS

uploadId: value of uploadId returned from the upload call
spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path (destination) of the file
hash: encoded hash of the file
modified: last modified timestamp in epoch time
seq: (optional) expected sequence number of path

RETURNS

New sequence number and content information as a result of this operation.

SAMPLE JSON RESPONSE

{ "seq": 2050, "contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "modified": 1373566588, "size": 100 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
204: Parent folder not found.
214: Invalid file size.
215: Invalid modified timestamp.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.
540: Not enough available storage.
601: File was not uploaded (e.g. /upload was not called, or uploadId not found, or upload session has expired).


/rest/files/add_folder

DESCRIPTION

Creates a new folder.

GET  /rest/files/add_folder?path=/a/b/newfolder

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path (destination) of the new folder
seq: (optional) expected sequence number of parent folder

RETURNS

New sequence number as a result of this operation.

SAMPLE JSON RESPONSE

{ "seq": 2051 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
204: Parent folder not found.
205: Path already exists.
222: Path is not in a valid format, or new folder name is invalid.
341: Space not found.
406: You do not have permission to modify the space.


/rest/files/move

DESCRIPTION

Moves an existing file or folder to an existing folder in the cloud.

GET  /rest/files/move?srcpath=/a/b/somefile.txt&dstpath=/a/c/somefile.txt

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
srcpath: absolute path (source) of the file/folder
dstpath: absolute path (destination) of the file/folder
seq: (optional) expected sequence number of srcpath
dstseq: (optional) expected sequence number of parent folder of dstpath

RETURNS

New sequence number as a result of this operation, and contentId and modified and size values if srcpath is a file.

SAMPLE JSON RESPONSE

{ "seq": 2052, "contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "modified": 1373566588, "size": 100 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
202: Source path not found.
204: Destination parent folder not found.
205: Destination path already exists.
209: Invalid move: parent folder to its own children path.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.


/rest/files/copy

DESCRIPTION

Copies an existing file to an existing folder in the cloud.

GET  /rest/files/copy?srcpath=/a/b/somefile.txt&dstpath=/a/c/somefile.txt

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
srcpath: absolute path (source) of the file
dstpath: absolute path (destination) of the file
seq: (optional) expected sequence number of srcpath
dstseq: (optional) expected sequence number of parent folder of dstpath

RETURNS

New sequence number as a result of this operation, and newly created file's contentId and modified and size values.

SAMPLE JSON RESPONSE

{ "seq": 2053, "contentId": "69d06391-9477-47a5-a846-a0685ae0ba6b", "modified": 1373566588, "size": 100 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
202: Source path not found.
203: Path is not a file.
204: Destination parent folder not found.
205: Destination path already exists.
222: Path is not in a valid format, or file name is invalid.
341: Space not found.
406: You do not have permission to modify the space.


/rest/files/delete

DESCRIPTION

Removes the file or folder from the cloud.

GET  /rest/files/delete?path=/a/b/proposal.doc

PARAMETERS

spaceOid: (optional) id of the space where content is located (blank means Oxygen drive root)
path: absolute path of the file
seq: (optional) expected sequence number of path

RETURNS

New sequence number as a result of this operation.

SAMPLE JSON RESPONSE

{ "seq": 2054 }

ERROR CODES

200: Invalid sequence number, or expected sequence number mismatch.
202: Path not found.
207: File or folder already deleted.
222: Path is not in a valid format.
341: Space not found.
406: You do not have permission to modify the space.


Synchronize

/rest/sync/get_latest_seqNumber

DESCRIPTION

Get the latest sequence number for a space.

GET  /rest/sync/get_latest_seqNumber?spaceOid=a8d931b2-e29d-4bbe-93f0-8f140a82dd10-51c9f2ab

PARAMETERS

spaceOid: (optional) id of the space where content is being tracked by sequence number (blank means Oxygen drive root)

RETURNS

The latest sequence number.

SAMPLE JSON RESPONSE

{ "latestSeq": 300 }

ERROR CODES

341: Space not found.
406: You do not have permission to view the space.


Subscribed Spaces

/rest/spaces/list_spaces

DESCRIPTION

Lists spaces that you subscribe to.

GET  /rest/spaces/list_spaces

PARAMETERS

None

RETURNS

List of subscribed spaces.

SAMPLE JSON RESPONSE

{ "spaces": [
  {"name": "", "type": "space", "oid" : "uv-52ba11ab-9883-4388"},
  {"name": "MyDocs", "type": "space", "oid" : "8a8a8af43c26ff10013c27001db70002"}
] }

ERROR CODES

None


/rest/spaces/get_space

DESCRIPTION

Gets basic info on a space that you subscribe to.

GET  /rest/spaces/get_space?space=MyDocs

PARAMETERS

space: (optional) name of the space (blank means Oxygen drive root)

RETURNS

Space information.

SAMPLE JSON RESPONSE

{ "oid": "8a8a8af43c26ff10013c27001db70002", "type": "space" "name": "MyDocs", }

ERROR CODES

341: Space not found.


Manage Account

/rest/account/get_account

DESCRIPTION

Get basic info about your account.

GET  /rest/account/get_account

PARAMETERS

None

RETURNS

Account information.

SAMPLE JSON RESPONSE

{ "name": "XYZ Company", "created": 1372289351 }

ERROR CODES

406: You do not have administrative permission to do this.


Manage Users

/rest/account/list_users

DESCRIPTION

List users in your account.

GET  /rest/account/list_users

PARAMETERS

None

RETURNS

Information about users in your account.

SAMPLE JSON RESPONSE

{ "data": [
  {"name": "John Doe", "id": "john_doe@xyzcompany.com", "email": "john_doe@xyzcompany.com", "enabled": true, "created": 1373341002}
  {"name": "Jane Goh", "id": "jane_goh@xyzcompany.com", "email": "jane_goh@xyzcompany.com", "enabled": true, "created": 1373342001},
] }

ERROR CODES

406: You do not have administrative permission to do this.


/rest/account/get_user

DESCRIPTION

Lookup user in your account.

GET  /rest/account/get_user?id=john_doe@xyzcompany.com

PARAMETERS

id: user Oxygen ID

RETURNS

Information about user.

SAMPLE JSON RESPONSE

{ "name": "John Doe", "id": "john_doe@xyzcompany.com", "email": "john_doe@xyzcompany.com", "enabled": true, "created": 1373341002 }

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.


/rest/account/add_user

DESCRIPTION

Create new user for your account.

GET  /rest/account/add_user?id=bob_jones@xyzcompany.com&email=bob_jones@xyzcompany.com&firstName=Bob&lastName=Jones&password=NEW_PASSWORD

PARAMETERS

id: unique Oxygen ID
email: user email address
firstName: user first name
lastName: user last name
password: new user's password (required if account is non-LDAP, ignored is account is LDAP)

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

322: A user with this id or email already exists.
406: You do not have administrative permission to do this.
540: Not enough available storage to create a space for the new user.


/rest/account/update_user

DESCRIPTION

Update user information.

GET  /rest/account/update_user?id=bob_jones@xyzcompany.com&email=robert_jones@xyzcompany.com&firstName=Robert

PARAMETERS

id: user Oxygen ID
email: (optional) new email address
firstName: (optional) new first name
lastName: (optional) new last name

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
322: A user with this email already exists.
406: You do not have administrative permission to do this.


/rest/account/enable_user

DESCRIPTION

Enable user in your account.

GET  /rest/account/enable_user?id=bob_jones@xyzcompany.com

PARAMETERS

id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.


/rest/account/disable_user

DESCRIPTION

Disable user in your account.

GET  /rest/account/disable_user?id=bob_jones@xyzcompany.com

PARAMETERS

id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.


/rest/account/delete_user

DESCRIPTION

Delete user from your account.

GET  /rest/account/delete_user?id=bob_jones@xyzcompany.com

PARAMETERS

id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.


Manage Groups

/rest/account/list_groups

DESCRIPTION

List groups in your account.

GET  /rest/account/list_groups

PARAMETERS

None

RETURNS

Information about groups in your account.

SAMPLE JSON RESPONSE

{ "data": [
  {"name": "Administrators", created": 1373341002}
  {"name": "Everyone", created": 1373341618}
  {"name": "Marketing", "created": 1373342001},
] }

ERROR CODES

406: You do not have administrative permission to do this.


/rest/account/get_group

DESCRIPTION

Lookup group in your account.

GET  /rest/account/get_group?group=Marketing

PARAMETERS

group: group name

RETURNS

Information about group.

SAMPLE JSON RESPONSE

{ "name": "Marketing", "created": 1373341002 }

ERROR CODES

331: Group not found.
406: You do not have administrative permission to do this.


/rest/account/add_group

DESCRIPTION

Create new group for your account.

GET  /rest/account/add_group?name=Engineers

PARAMETERS

name: unique group name

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

332: A group with this name already exists.
406: You do not have administrative permission to do this.


/rest/account/update_group

DESCRIPTION

Update group information.

GET  /rest/account/update_group?group=Marketing&name=Vanguard

PARAMETERS

group: group name
name: new name for group

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

331: Group not found.
332: A group with this name already exists.
406: You do not have administrative permission to do this.


/rest/account/delete_group

DESCRIPTION

Delete group from your account.

GET  /rest/account/delete_group?group=Engineers

PARAMETERS

group: group name

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

331: Group not found.
406: You do not have administrative permission to do this, or if the group is a system group and cannot be deleted.


/rest/account/list_group_users

DESCRIPTION

List users in the group.

GET  /rest/account/list_group_users?group=Marketing

PARAMETERS

group: group name

RETURNS

Information about users in the group.

SAMPLE JSON RESPONSE

{ "data": [
  {"name": "John Doe", "id": "john_doe@xyzcompany.com", "email": "john_doe@xyzcompany.com"}
  {"name": "Jane Goh", "id": "jane_goh@xyzcompany.com", "email": "jane_goh@xyzcompany.com"},
] }

ERROR CODES

331: Group not found.
406: You do not have administrative permission to do this.


/rest/account/add_group_user

DESCRIPTION

Add a user to the group.

GET  /rest/account/add_group_user?group=Engineers&id=bob_jones@xyzcompany.com

PARAMETERS

group: group name
id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
331: Group not found.
406: You do not have administrative permission to do this.


/rest/account/delete_group_user

DESCRIPTION

Remove a user from group.

GET  /rest/account/delete_group_user?group=Engineers&id=bob_jones@xyzcompany.com

PARAMETERS

group: group name
id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
331: Group not found.
406: You do not have administrative permission to do this.


/rest/account/list_group_permissions

DESCRIPTION

List group permissions.

GET  /rest/account/list_group_permissions?group=Marketing

PARAMETERS

group: group name

RETURNS

Information about group permissions.

SAMPLE JSON RESPONSE

{ "data": [
  {"permission": "admin", "enabled" : false},
  {"permission": "create_space", "enabled" : true, "capacity": 2},
  {"permission": "perm_delete", "enabled" : false},
  {"permission": "invite_guests", "enabled" : true},
  {"permission": "share_files", "enabled" : true}
] }

ERROR CODES

331: Group not found.
406: You do not have administrative permission to do this.


/rest/account/enable_group_permission

DESCRIPTION

Enable group permission.

GET  /rest/account/enable_group_permission?group=Engineers&permission=create_space

PARAMETERS

group: group name
permission: permission id (see /list_group_permissions)

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

107: No such permission id.
331: Group not found.
406: You do not have administrative permission to do this, or if a system group permission cannot be changed.


/rest/account/disable_group_permission

DESCRIPTION

Disable group permission.

GET  /rest/account/disable_group_permission?group=Engineers&permission=create_space

PARAMETERS

group: group name
permission: permission id (see /list_group_permissions)

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

107: No such permission id.
331: Group not found.
406: You do not have administrative permission to do this, or if a system group permission cannot be changed.


Manage Spaces

/rest/spaces/list_account_spaces

DESCRIPTION

Lists all spaces in the account.

GET  /rest/spaces/list_account_spaces

PARAMETERS

None

RETURNS

List of all spaces in the account.

SAMPLE JSON RESPONSE

{ "spaces": [
  {"name": "MyDocs", "type": "space", "oid" : "8a8a8af43c26ff10013c27001db70002"},
  {"name": "Inbox", "type": "space", "oid" : "7fd5e0111c404ce19d8a08683b46d654"}
] }

ERROR CODES

406: You do not have administrative permission to do this.


/rest/spaces/get_account_space

DESCRIPTION

Lookup a space in the account.

GET  /rest/spaces/get_account_space?space=MyDocs

PARAMETERS

space: name of the space

RETURNS

Space information, where "created" is time in seconds since epoch, and "utilized" (and "capacity", if applicable) are in GB.

SAMPLE JSON RESPONSE

{ "oid": "8a8a8af43c26ff10013c27001db70002", "type": "space", "name": "MyDocs", "description": "My documents", "owner": "John Doe", "created": 1357863984, "listed": false, "storage": "Default Cloud (Oxygen Storage Connector)", "utilized": 0.533 }

ERROR CODES

341: Space not found.
406: You do not have administrative permission to do this.


/rest/spaces/update_account_space

DESCRIPTION

Update space information.

GET  /rest/spaces/update_account_space?space=Inbox&name=Incoming

PARAMETERS

space: name of the space
name: (optional) new space name
capacity: (optional) new maximum storage quota capacity for the space (in GB)

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

341: Space not found.
342: A space with this name already exists.
406: You do not have permission to manage this space.
540: Not enough available storage.


/rest/spaces/get_user_space

DESCRIPTION

Get basic information about user Oxygen Drive root space for a particular user.

GET  /rest/spaces/get_user_space?id=john_doe@xyzcompany.com

PARAMETERS

id: user Oxygen ID

RETURNS

Space information, where "created" is time in seconds since epoch, and "utilized" (and "capacity", if applicable) are in GB.

SAMPLE JSON RESPONSE

{ "oid": "uv-52ba11ab-9883-4388", "type": "space" "owner": "John Doe", "created": 1350338093, "storage": "Default Cloud (Oxygen Storage Connector)", "capacity": 2, "utilized": 1.058 }

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.


/rest/spaces/update_user_space

DESCRIPTION

Update information of a user Oxygen Drive root space for a particular user.

GET  /rest/spaces/update_user_space?id=john_doe@xyzcompany.com&capacity=5

PARAMETERS

id: user Oxygen ID
capacity: new maximum storage quota capacity for the space (in GB)

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
406: You do not have administrative permission to do this.
540: Not enough available storage.


/rest/spaces/add_space

DESCRIPTION

Create a new space in the account.

GET  /rest/spaces/add_space?name=Inbox&capacity=5

PARAMETERS

name: name of the space
capacity: (optional) maximum storage quota capacity for the space (in GB)

RETURNS

Space information.

SAMPLE JSON RESPONSE

{ "oid": "7fd5e0111c404ce19d8a08683b46d654", "type": "space" "name": "Inbox" }

ERROR CODES

342: A space with this name already exists.
406: You do not have permission to create a space.
540: Not enough available storage.


/rest/spaces/delete_space

DESCRIPTION

Deletes space in the account.

GET  /rest/spaces/delete_space?space=Inbox

PARAMETERS

space: name of the space

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

341: Space not found.
406: You do not have permission to manage this space.


Manage Subscriptions

/rest/spaces/list_space_subscriptions

DESCRIPTION

Lists all subscriptions in a space.

GET  /rest/spaces/list_space_subscriptions?space=Inbox

PARAMETERS

space: name of the space

RETURNS

List of all spaces in the account.

SAMPLE JSON RESPONSE

{ "subscriptions": [
  {"subscriber": "John Doe", "type": "user", "oid": "ff8080813f10c3df013f10e0be570103", "canWrite": true, "canManage": true},
  {"subscriber": "Marketing", "type": "group", "canWrite": true, "canManage": false}
] }

ERROR CODES

341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/add_user_subscription

DESCRIPTION

Subscribe a user to a space.

GET  /rest/spaces/add_user_subscription?space=Inbox&id=bob_jones@xyzcompany.com&canWrite=true&canManage=false

PARAMETERS

space: name of the space
id: user Oxygen ID
canWrite: grant/revoke write permission on the space for the new subscription
canManage: grant/revoke manage permission on the space for the new subscription

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/update_user_subscription

DESCRIPTION

Update a user's subscription to a space.

GET  /rest/spaces/update_user_subscription?space=Inbox&id=bob_jones@xyzcompany.com&canWrite=true&canManage=false

PARAMETERS

space: name of the space
id: user Oxygen ID
canWrite: grant/revoke write permission on the space for the subscription
canManage: grant/revoke manage permission on the space for the subscription

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/delete_user_subscription

DESCRIPTION

Unsubscribe a user from a space.

GET  /rest/spaces/delete_user_subscription?space=Inbox&id=bob_jones@xyzcompany.com

PARAMETERS

space: name of the space
id: user Oxygen ID

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

321: User not found.
341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/add_group_subscription

DESCRIPTION

Subscribe a group to a space.

GET  /rest/spaces/add_group_subscription?space=Inbox&group=Engineers&canWrite=false&canManage=false

PARAMETERS

space: name of the space
group: group name
canWrite: grant/revoke write permission on the space for the new subscription
canManage: grant/revoke manage permission on the space for the new subscription

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

331: Group not found.
341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/update_group_subscription

DESCRIPTION

Update a group's subscription to a space.

GET  /rest/spaces/update_group_subscription?space=Inbox&group=Engineers&canWrite=false&canManage=false

PARAMETERS

space: name of the space
group: group name
canWrite: grant/revoke write permission on the space for the subscription
canManage: grant/revoke manage permission on the space for the subscription

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

331: Group not found.
341: Space not found.
406: You do not have permission to manage this space.


/rest/spaces/delete_group_subscription

DESCRIPTION

Unsubscribe a group from a space.

GET  /rest/spaces/delete_group_subscription?space=Inbox&group=Engineers

PARAMETERS

space: name of the space
group: group name

RETURNS

HTTP 200 response indicates successful operation

SAMPLE HTTP RESPONSE

HTTP/1.1 200 OK

ERROR CODES

331: Group not found.
341: Space not found.
406: You do not have permission to manage this space.