Configuring workspaces in Management API

Prerequisites

Before you complete the procedures in this guide, perform the following action:

• Use a Connect API key with the following permissions:

  • Workspace: Read-only (workspace:read) to retrieve information about a workspace.

  • Workspace: Write (workspace:write) to update a workspace.

  Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

Retrieving information about existing workspace

To retrieve information about an existing workspace, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/
   

   {{STACK_SLUG}}: Represents a slugified name of your workspace. Find the {{STACK_SLUG}} as value of parameter slug in the response of the API call where you list existing workspaces. To obtain this API response, follow the procedure in Listing existing workspaces.

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

As a result, you retrieved information about a workspace. Use the retrieved information to edit the workspace configuration in the following section Configuring a workspace in Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/' \
--header 'Authorization: Bearer {{KEY}}'

Configuring a workspace in Management API

The following procedure explains how to change the parent workspace for your selected workspace. You can edit other options as the name of your workspace.

To configure your workspace through the Management API, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following code as raw JSON input, and then replace the placeholder values as necessary.

   {
      "parent_id":PARENT_ID
   }
   

   Replace PARENT_ID with the parent workspace ID. This means that another workspace becomes the parent of the workspace that you are configuring and inherits some of its configuration. Your workspace already has a default parent workspace. To find the PARENT_ID, search for the value of the parameter id in an API call described in the section Listing existing workspaces.

5. Send the request.

As a result, you changed the parent of the selected workspace. With this procedure, you can edit names of workspaces and other details.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request PATCH 'https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"parent_id":PARENT_ID}'