Group / Plan Manipulation

All the methods described on this page require the partner to be authenticated.

List Plans

GET /plans

List existing plans.

Returns a JSON list of objects containing the following information:

JSON Parameters:  

• plan_id (int) – The plan_id of the plan.
• storage_bytes (int) – The plan storage quota, in bytes.

List Groups

GET /groups/

List existing groups.

Query Parameters:  

• search – Optional. Limit results to groups whose name contains this text.

Returns a JSON list of objects containing the same information as Group Info, below.

Create Group

POST /groups/

Create a new group.

Request must include a JSON object containing all parameters listed in Group Info, below.

Possible response status codes are:

Status Codes:

• 201 – Group created successfully. The Location header will indicate the new group’s group_id.
• 400 – Invalid request parameters were included.
• 409 – Attempted to set plan_id parameter to a nonexistent plan_id, or a group with the provided name already exists.

Group Info

GET /groups/(group_id)

POST /groups/(group_id)

View or modify group information. A GET request will return current values for the below parameters, while a POST request will set them. You may include any number of the parameters below in a POST request.

JSON Parameters:  

• name (string) – The group name.
• plan_id (int) – The plan_id of the plan to associate users in this group with.
• webapi_enable (bool) – Are users in this group allowed to access their data via the web interface?
• check_domain (bool) – Restrict client installs to machines in the ActiveDirectory domain set in Enterprise Settings.
• force (bool) – (POST only) Force setting the plan_id for the group even if it would cause avatars within the group to exceed their storage quota.

The following response statuses are possible:

Status Codes:

• 200 – Information retrieved/updated successfully.
• 404 – A group with the given group_id could not be found.
• 400 – (POST only) Invalid request parameters were included.
• 402 – (POST only) Attempted to set plan_id parameter that would cause space allocation to go beyond the available amount.
• 409 – (POST only) Attempted to set plan_id parameter to a nonexistent plan_id, or a group with the specified name already exists. Also returned when attempting to change the plan_id to a plan that would cause avatars in this group to exceed their quota. Use the force option to change the plan anyway.

Deleting Groups

DELETE /groups/(group_id)

POST /groups/(group_id)?action=delete

Delete the specified group.

This action is available using either the HTTP DELETE method, or POST with the ?action=delete query parameter.

Query Parameters:  

• move_to – Optional. The group_id of the group to move users to. Moves all users of this group to the group specified in move_to. This parameter is required if this group contains any users.

The following response statuses are possible:

Status Codes:

• 200 – Group was deleted successfully.
• 404 – A group with the given group_id could not be found.
• 409 – The group contains users and the move_to paramater was not supplied.