Workspaces

Workspaces help users to organize, maintain, and store project data. Workspaces can be managed using the workspace service API.

In order to use these endpoints, you will need to obtain an authorization token and find your Evo organisation ID. For more information, see Apps and tokens and Evo Discovery.

Creating a workspace

POST https://<service_host>/workspace/orgs/<org_id>/workspaces

You can create a workspace by performing a POST request to the workspaces endpoint of a given organization. The request must contain a valid "create workspace" request body, filled with relevant metadata about the workspace.

import requests

create_workspace_body = {
    "bounding_box": {
        "type": "Polygon",
        "coordinates": [
            [
                [100.0, 0.0],
                [101.0, 0.0],
                [101.0, 1.0],
                [100.0, 1.0],
                [100.0, 0.0]
            ]
        ]
    },
    "default_coordinate_system": "EPSG:7642",
    "description": "",
    "name": "My new workspace"
}

response = requests.post(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces",
    json=create_workspace_body,
    headers={ "Authorization": "Bearer [yourtokenhere]" },
)
print(response.json())

Retrieving a workspace

GET https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>

You can retrieve a workspace by performing a GET request for a particular workspace ID as follows:

import requests

response = requests.get(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)
print(response.json())

Listing workspaces

GET https://<service_host>/workspace/orgs/<org_id>/workspaces

You can request a paginated list of all workspaces under a given organization by performing a GET request on the workspaces endpoint for that organization. Control the number of workspaces returned (limit), and the position to begin listing workspaces (offset) using request parameters.

import requests

response = requests.get(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces?limit=20&offset=0",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)
print(response.json())

Filters

To narrow down a set of results, a number of filtering options are available:

• filter[user_id]: user ID with permission to access the workspace
• filter[created_by]: user ID that created the workspace
• filter[created_at]: workspaces creation time (operators: eq, lt, lte, gt, gte)
• filter[updated_at]: workspaces last updated time (operators: eq, lt, lte, gt, gte)
• name=[operator]:[value] workspaces name (operators: eq)
• deleted workspace deletion status

For example, to filter by deleted workspaces created after Jan 1st, 2024:

import requests

response = requests.get(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces?deleted=true&filter[created_at]=gt:2024-01-01T00:00:00Z",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)
print(response.json())

Sorting

Workspaces may be sorted in a particular order using the order_by request parameter. The following sorting criterion exist:

• name: Sort by name in ascending order
• desc:name: Sort by name in descending order
• created_at: Sort by their created time in ascending order
• desc:created_at: Sort by their created time in descending order
• updated_at: Sort by their updated time in ascending order
• desc:updated_at: Sort by their updated time in descending order
• user_role: Sort by user role in ascending order
• desc:user_role: Sort by user role in descending order

For example, to show the most recently created workspaces first:

import requests

response = requests.get(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces?order_by=desc:created_at",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)
print(response.json())

Updating a workspace

PATCH https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>

To update a workspace's data, perform a PATCH request using the same request body as the "create workspace" endpoint.

For example, to change a workspace's name and description:

import requests

payload = {
    "name": "My updated example workspace",
    "description": "An updated description here"
}

response = requests.patch(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>",
    json=payload,
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)
print(response.json())

Deleting a workspace

DELETE https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>

A workspace can be deleted using a DELETE request. A successful request will return a 204 No Content status code, as will subsequent requests to delete the same workspace.

import requests

requests.delete(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)

Deleted workspaces will no longer be returned in "get workspace" and "list workspaces" API requests. If you want them to be included, you can append deleted=true to your request parameters for these endpoints.

Restoring a deleted workspace

POST https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>?deleted=false

You can restore a soft deleted workspace with a POST request. You must have an "owner" role in the workspace to perform this request.

A successful request results in a 204 No Content status code, as will subsequent restore requests on an active (non-deleted) workspace.

If there is a naming conflict with the workspace name, a suffix will be used to rename the workspace with maximum version number. For example, restoring a deleted workspace named "ws" while "ws", "ws (1)" and "ws (6)" are active, will cause the workspace to be renamed as "ws (7)".

import requests

requests.post(
    f"https://<service_host>/workspace/orgs/<org_id>/workspaces/<workspace_id>?deleted=false",
    headers={ "Authorization": "Bearer [yourtokenhere]" }
)