Mavenlink

Workspace Groups

Workspace Groups (also know as project groups) allow for the categorization of Mavenlink Workspaces. Workspace Groups are unique to each Mavenlink Account.

Workspace Group objects have the following readable attributes:

  • id - the internal workspace group ID
  • name - the name of the workspace group
  • company - whether the workspace group represents a company

Fetching Workspace Groups

You can access all of the workspace groups on the authorizing user's account through the API as follows:

curl "https://api.mavenlink.com/api/v1/workspace_groups.json"

The resulting JSON will be an array of objects. The entries will be sorted by the created_at field in descending order by default.

Associated Objects

You can include workspace groups' associations with the include param. For example, to include returned workspace groups' workspaces, you would do the following:

curl "https://api.mavenlink.com/api/v1/workspace_groups.json?include=workspaces"

In this example, our API will ensure that the returned JSON contains top-level keys called workspaces where you can find associated data by inspecting workspace groups' workspace_ids field. See Object Associations to learn more. The following associations can be requested through the API:

  • workspaces - the workspaces (projects) that are associated with the workspace group, returned in the workspaces top-level key

Ordering Workspace Groups

Valid orders are:

  • updated_at
  • created_at

The default order is created_at:desc.

Getting a Single Workspace Group

As with all resources, you can request either GET /api/v1/workspaces_groups.json?only=5 or GET /api/v1/workspace_groups/5.json.

Creating a new Workspace Group

You can create a workspace group with the follow parameters:

  • name - (required) the name of the new workspace group. Names must be unique and are not case sensitive. (ie: an account cannot both have a workspace group named "Mavenlink" and another named "mavenlink")
  • company - (optional) a boolean that indicates whether or not the workspace group represents a company; default is false
  • add_workspace_ids - (optional) an array of Workspace IDs that is associated with the workspace group. The authorizing user must have access to all given workspaces

You can create workspace groups through the API as follows:

curl  -d "workspace_group[name]=New Workspace Group" -d "workspace_group[company]=false" "https://api.mavenlink.com/api/v1/workspace_groups.json"

The response will contain a JSON representation of the newly created workspace group or an error message indicating which arguments are missing or erroneous.

Updating an existing Workspace Group

You can edit a Workspace Group as follows:

curl -X PUT -d "workspace_group[name]=new name" "https://api.mavenlink.com/api/v1/workspace_groups/2.json"

When updating a workspace group you can optionally modify the following attributes:

  • name
  • company
  • add_workspace_ids - an array of Workspace IDs to be associated with the workspace group. Workspaces already associated with the workspace group will retain association. The authorizing user must have access to all the given workspaces
  • remove_workspace_ids - an array of Workspace IDs to be disassociated with the workspace group. The authorizing user must have access to all the given workspaces

Destroying an existing Workspace Group

You can delete Workspace Groups as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/workspace_groups/1.json"

The response will have no content and HTTP 204 status code if the Workspace Group has been successfully deleted, or a JSON error message indicating why the Workspace Group could not be deleted.