Workspaces

Endpoints for managing and maintaining workspaces in an organization

List workspaces

Workspaces API

Returns a paginated list of all workspaces that you have a role to access in your organization. For a list of all workspaces regardless of your user role, see the 'Admin' equivalent API.

Parameters

user-agentstring

authorizationstring

Required

org_iduuid

Required

Default: 20

The maximum number of results to return. Limits over 100 are deprecated and may only work for some clients.

The (zero-based) offset of the first item returned in the collection.

An optional comma separated list of fields to sort the results by. Options are: name, -name, created_at, -created_at, updated_at, -updated_at, user_role, -user_role.

An optional, comma-separated list of fields by which to order the results. Each field could be prefixed with an order operator: asc: for ascending order or desc: for descending order, default is ascending order. The sortable fields are: name, created_at, updated_at, and user_role. You can also do compound sorts by comma separating your order params, e.g. asc:user_role,desc:name. This will sort by user_role in ascending order and then by name in descending order as a secondary sort.

Filter by workspace that a user has created, by user ID.

Filter by the time workspace has created.

Filter by the latest time workspace was updated.

Filter by workspace name.

Include workspaces that have been deleted.

Filter by workspaces that a user ID has access to.

Returns

200

Successful Response

countinteger

firsturi

[1, 2,083] chars

lasturi

[1, 2,083] chars

nexturi | null

[1, 2,083] chars

previousuri | null

[1, 2,083] chars

totalinteger

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer" | null

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer" | null

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

thumbnail_linkuri | null

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

Endpoint

GET

/workspace/orgs/{org_id}/workspaces

Request

curl -X GET 'https://{service_host}/workspace/orgs/{org_id}/workspaces' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "links": {
    "count": 0,
    "first": "https://example.com",
    "last": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com",
    "total": 0
  },
  "results": [
    {
      "bounding_box": {
        "coordinates": [
          [
            [
              0,
              0
            ]
          ]
        ],
        "type": "Polygon"
      },
      "created_at": "2024-07-29T15:51:28.071Z",
      "created_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "current_user_role": "owner",
      "default_coordinate_system": "",
      "description": "",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "labels": [
        "string"
      ],
      "ml_enabled": false,
      "name": "string",
      "self_link": "https://example.com",
      "updated_at": "2024-07-29T15:51:28.071Z",
      "updated_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      }
    }
  ]
}

Create workspace

Workspaces API

Version: 1.0

Creates a new workspace in your organization.

Parameters

user-agentstring

authorizationstring

Required

org_iduuid

Required

Example: {"coordinates":[[[100,0],[101,0],[101,1],[100,1],[100,0]]],"type":"Polygon"}

The geographic bounding box for the workspace, defined as a GeoJSON Polygon using the WGS 84 coordinate system (longitude, latitude). The polygon must be a rectangle defined by 5 coordinate pairs in counter-clockwise order. The first and last coordinate pairs must be identical to form a closed ring. Longitude values must be between -180 and 180, and latitude values must be between -90 and 90.

type"Polygon"

Required

null

The default coordinate reference system for the workspace. This can be either an EPSG code (for example, EPSG:4326), or a WKT2 coordinate reference system definition string (conforming to OGC / ISO standards).

descriptionstring

A list of labels

The name of the workspace, unique within an organization and hub

{
  "bounding_box": {
    "coordinates": [
      [
        [
          0,
          0
        ]
      ]
    ],
    "type": "Polygon"
  },
  "default_coordinate_system": "",
  "description": "",
  "labels": [
    "string"
  ],
  "name": "string"
}

Returns

201

Successful Response

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

thumbnail_linkuri | null

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

Endpoint

POST

/workspace/orgs/{org_id}/workspaces

Request

curl -X POST 'https://{service_host}/workspace/orgs/{org_id}/workspaces' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "bounding_box": {
    "coordinates": [
      [
        [
          0,
          0
        ]
      ]
    ],
    "type": "Polygon"
  },
  "created_at": "2024-07-29T15:51:28.071Z",
  "created_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "current_user_role": "owner",
  "default_coordinate_system": "",
  "description": "",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "labels": [
    "string"
  ],
  "ml_enabled": false,
  "name": "string",
  "self_link": "https://example.com",
  "updated_at": "2024-07-29T15:51:28.071Z",
  "updated_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  }
}

List workspaces summary

Workspaces API

Version: 1.0

List workspaces summary

Parameters

authorizationstring

Required

org_iduuid

Required

The maximum number of results to return.

The (zero-based) offset of the first item returned in the collection.

An optional comma separated list of fields to sort the results by. Options are: name, -name, created_at, -created_at, updated_at, -updated_at, user_role, -user_role.

Filter by workspace that a user has created, by user ID.

Filter by the time workspace has created.

Filter by the latest time workspace was updated.

Filter by workspace name.

Include workspaces that have been deleted.

Filter by workspaces that a user ID has access to.

Returns

200

Successful Response

countinteger

firsturi

[1, 2,083] chars

lasturi

[1, 2,083] chars

nexturi | null

[1, 2,083] chars

previousuri | null

[1, 2,083] chars

totalinteger

iduuid

The name of the workspace, unique within an organization and hub

Endpoint

GET

/workspace/orgs/{org_id}/workspaces/summary

Request

curl -X GET 'https://{service_host}/workspace/orgs/{org_id}/workspaces/summary' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "links": {
    "count": 0,
    "first": "https://example.com",
    "last": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com",
    "total": 0
  },
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    }
  ]
}

Delete workspace

Workspaces API

Version: 1.0

Deletes a workspace. Use of this API requires an "owner" role in the workspace. Deleted workspaces will no longer be returned in "get workspace" and "list workspace" requests, however you can include them by appending deleted=true to your request parameters.

Parameters

authorizationstring

Required

workspace_iduuid

Required

org_iduuid

Required

Returns

204

Successful Response

Endpoint

DELETE

/workspace/orgs/{org_id}/workspaces/{workspace_id}

Request

curl -X DELETE 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

No response body.

Get workspace

Workspaces API

Version: 1.0

Returns a workspace by its ID, provided your user has a role to access it. To retrieve a workspace by ID regardless of your user role, see the 'Admin' equivalent API.

Parameters

user-agentstring

authorizationstring

Required

org_iduuid

Required

workspace_iduuid

Required

Only list workspaces that have been deleted.

Returns

200

Successful Response

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer" | null

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

thumbnail_linkuri | null

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer" | null

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

thumbnail_linkuri | null

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

Endpoint

GET

/workspace/orgs/{org_id}/workspaces/{workspace_id}

Request

curl -X GET 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "bounding_box": {
    "coordinates": [
      [
        [
          0,
          0
        ]
      ]
    ],
    "type": "Polygon"
  },
  "created_at": "2024-07-29T15:51:28.071Z",
  "created_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "current_user_role": "owner",
  "default_coordinate_system": "",
  "description": "",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "labels": [
    "string"
  ],
  "ml_enabled": false,
  "name": "string",
  "self_link": "https://example.com",
  "updated_at": "2024-07-29T15:51:28.071Z",
  "updated_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  }
}

Update workspace

Workspaces API

Version: 1.0

Updates a workspace.

Parameters

user-agentstring

authorizationstring

Required

org_iduuid

Required

workspace_iduuid

Required

Example: {"coordinates":[[[100,0],[101,0],[101,1],[100,1],[100,0]]],"type":"Polygon"}

type"Polygon"

Required

null

descriptionstring | null

A list of labels

namestring | null

[1, 60] chars

{
  "bounding_box": {
    "coordinates": [
      [
        [
          0,
          0
        ]
      ]
    ],
    "type": "Polygon"
  },
  "default_coordinate_system": "string",
  "description": "string",
  "labels": [
    "string"
  ],
  "name": "string"
}

Returns

200

Successful Response

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

type"Polygon"

null

created_atdate-time

emailstring | null

iduuid

namestring | null

current_user_role"owner" | "editor" | "viewer"

default_coordinate_systemstring

descriptionstring

iduuid

labelsstring[]

Default: []

ml_enabledboolean

The name of the workspace, unique within an organization and hub

self_linkuri

[1, 2,083] chars

thumbnail_linkuri | null

[1, 2,083] chars

updated_atdate-time

emailstring | null

iduuid

namestring | null

Endpoint

PATCH

/workspace/orgs/{org_id}/workspaces/{workspace_id}

Request

curl -X PATCH 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "bounding_box": {
    "coordinates": [
      [
        [
          0,
          0
        ]
      ]
    ],
    "type": "Polygon"
  },
  "created_at": "2024-07-29T15:51:28.071Z",
  "created_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "current_user_role": "owner",
  "default_coordinate_system": "",
  "description": "",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "labels": [
    "string"
  ],
  "ml_enabled": false,
  "name": "string",
  "self_link": "https://example.com",
  "updated_at": "2024-07-29T15:51:28.071Z",
  "updated_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  }
}

Restore a deleted workspace

Workspaces API

Version: 1.0

If a workspace has been soft deleted, this API allows you to restore it again. After restoring, the workspace will no longer be included in "get workspace" and "list workspace" when the deleted=true parameter is appended to your request parameters.

Parameters

authorizationstring

Required

workspace_iduuid

Required

org_iduuid

Required

deletedstring | null

Returns

204

Successful Response

Endpoint

POST

/workspace/orgs/{org_id}/workspaces/{workspace_id}

Request

curl -X POST 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

No response body.

Get current user role

Workspaces API

Version: 1.0

Returns your user account's role in a workspace.

Parameters

authorizationstring

Required

workspace_iduuid

Required

org_iduuid

Required

Returns

200

Successful Response

role"owner" | "editor" | "viewer"

user_iduuid

Endpoint

GET

/workspace/orgs/{org_id}/workspaces/{workspace_id}/current-user-role

Request

curl -X GET 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}/current-user-role' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "role": "owner",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

List users

Workspaces API

Version: 1.0

Returns a list of all users with a role in a workspace.

Parameters

authorizationstring

Required

workspace_iduuid

Required

org_iduuid

Required

Filter to see the role of a specific user ID.

Returns

200

Successful Response

linksLinks

emailstring | null

full_namestring | null

role"owner" | "editor" | "viewer"

user_iduuid

Endpoint

GET

/workspace/orgs/{org_id}/workspaces/{workspace_id}/users

Request

curl -X GET 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}/users' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "links": {
    "additionalProp1": "https://example.com",
    "additionalProp2": "https://example.com",
    "additionalProp3": "https://example.com"
  },
  "results": [
    {
      "email": "string",
      "full_name": "string",
      "role": "owner",
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}

Assign user role

Workspaces API

Version: 1.0

Assigns a user a role in a workspace.

Parameters

authorizationstring

Required

org_iduuid

Required

workspace_iduuid

Required

role"owner" | "editor" | "viewer"

Required

user_iduuid

Required

emailstring

Required

role"owner" | "editor" | "viewer"

Required

{
  "role": "owner",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Returns

201

Successful Response

role"owner" | "editor" | "viewer"

user_iduuid

Endpoint

POST

/workspace/orgs/{org_id}/workspaces/{workspace_id}/users

Request

curl -X POST 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}/users' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "role": "owner",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Remove user from workspace

Workspaces API

Version: 1.0

Removes a user by removing their role from the workspace.

Parameters

authorizationstring

Required

workspace_iduuid

Required

user_iduuid

Required

org_iduuid

Required

Returns

204

Successful Response

Endpoint

DELETE

/workspace/orgs/{org_id}/workspaces/{workspace_id}/users/{user_id}

Request

curl -X DELETE 'https://{service_host}/workspace/orgs/{org_id}/workspaces/{workspace_id}/users/{user_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

No response body.

List workspaces​

Parameters

Request headers

Request headers

Path parameters

Path parameters

Query parameters

Query parameters

limitinteger

offsetinteger

sortstring | nullDeprecated

order_bystring | null

filter[created_by]uuid | nullDeprecated

created_bystring | null

created_atstring | string[] | null

updated_atstring | string[] | null

filter[name]string | nullDeprecated

namestring | null

deletedboolean

filter[user_id]uuid | nullDeprecated

user_idstring | null

Returns

200

Schema

linksPaginationLinks

resultsWorkspaceRoleOptionalResponse[] | WorkspaceRoleOptionalResponseWithThumbnailLink[]

Any of:

array

bounding_boxBoundingBox | null

Any of:

BoundingBoxobject

coordinatesarray[]

Any of:

number

integer

created_byUserModelOptional

namestring[1, 60] chars

updated_byUserModelOptional

array

bounding_boxBoundingBox | null

Any of:

BoundingBoxobject

coordinatesarray[]

Any of:

number

integer

created_byUserModelOptional

namestring[1, 60] chars

updated_byUserModelOptional

Endpoint

Request

Response

Create workspace​

Parameters

Request headers

Request headers

Path parameters

Path parameters

Body parameters Required

Body parameters Required

bounding_boxBoundingBox | null

Any of:

BoundingBoxobject

coordinatesarray[]Required

Any of:

number

integer

default_coordinate_systemstring

labelsstring[] | null

namestringRequired[1, 60] chars

Example body

Example body

Returns

201

Schema

Any of:

WorkspaceRoleRequiredResponseobject

bounding_boxBoundingBox | null

Any of:

BoundingBoxobject

List workspaces

Create workspace

Body parameters
Required

List workspaces summary

Delete workspace

Get workspace