Workspaces API¶

Create and arrange workspaces and configure their storage. See Workspaces.

Paths are relative to https://<your-atlas-host>/api/v1. For the API key and headers every request needs, see Authentication.

Endpoint	What it does
POST /workspaces/	Create a new workspace
GET /workspaces/	List all workspaces (flat list ordered by tree path)
GET /workspaces/{workspace_id}	Get a workspace by ID
PATCH /workspaces/{workspace_id}	Update a workspace
DELETE /workspaces/{workspace_id}	Delete a workspace
GET /workspaces/{workspace_id}/move/preview	Preview the storage/access impact of a proposed move (read-only)
POST /workspaces/{workspace_id}/move	Move a workspace under a new parent
GET /workspaces/{workspace_id}/descendants	Get all descendants of a workspace
POST /workspace-storage/	Create storage configuration for a root workspace
GET /workspace-storage/	List all workspace storage configurations for your organization
GET /workspace-storage/{storage_id}	Get workspace storage by ID
PATCH /workspace-storage/{storage_id}	Update workspace storage configuration
DELETE /workspace-storage/{storage_id}	Delete workspace storage
GET /workspace-storage/workspace/{workspace_id}	Get storage configuration for a workspace (works for any depth)
POST /workspace-storage/{storage_id}/health-check	Run health check on workspace storage

Create workspace¶

POST /workspaces/

Create a new workspace.

Request body

Field	Type	Required	Description
`display_name`	string	Yes
`description`	string
`labels`	object		Key-value tags, usable in row filters as `workspace.labels.<key>`.
`parent_id`	UUID		Parent workspace; `null` creates a top-level one. Up to 10 levels deep.

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

List workspaces¶

GET /workspaces/

List all workspaces (flat list ordered by tree path).

Parameters

Name	In	Type	Description
`flat`	query	boolean	Return flat list vs roots only
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

Get workspace¶

GET /workspaces/{workspace_id}

Get a workspace by ID.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

Update workspace¶

PATCH /workspaces/{workspace_id}

Update a workspace.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes

Request body

Field	Type
`display_name`	string
`description`	string
`labels`	object

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

Delete workspace¶

DELETE /workspaces/{workspace_id}

Delete a workspace.

Parameters

Name	In	Type	Required	Description
`workspace_id`	path	UUID	Yes
`cascade`	query	boolean		Delete descendants too

Response

The raw file content.

Preview move workspace¶

GET /workspaces/{workspace_id}/move/preview

Preview the storage/access impact of a proposed move (read-only).

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes
`new_parent_id`	query	UUID
`position`	query	string

Response

Field	Type
`workspace_id`	UUID
`target_parent_id`	UUID
`position`	string
`valid`	boolean
`validation_errors`	list of string
`requires_confirmation`	boolean
`crosses_storage_anchor`	boolean
`storage_impact`	object
`access_impact`	object

Move workspace¶

POST /workspaces/{workspace_id}/move

Move a workspace under a new parent.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes

Request body

Field	Type	Description
`new_parent_id`	UUID	Workspace to move under; `null` makes it a top-level workspace.
`position`	string	Ignored; sibling order is set automatically.
`confirm_impact`	boolean	Confirm a move that changes storage or access; without it such a move returns 422 with the impact.

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

Get workspace descendants¶

GET /workspaces/{workspace_id}/descendants

Get all descendants of a workspace.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`labels`	object
`depth`	integer
`parent_id`	UUID
`children_count`	integer
`path`	string
`created_at`	datetime
`updated_at`	datetime

Create workspace storage¶

POST /workspace-storage/

Create storage configuration for a root workspace.

Request body

Field	Type	Required
`display_name`	string	Yes
`workspace_id`	UUID	Yes
`config_type`	string	Yes
`config`	object
`credentials`	object
`is_managed`	boolean
`region`	string

Response

Field	Type
`id`	UUID
`display_name`	string
`workspace_id`	UUID
`config_type`	string
`config`	object
`is_active`	boolean
`is_managed`	boolean
`region`	string
`health_status`	string
`last_health_check_at`	datetime
`created_at`	datetime
`updated_at`	datetime

List workspace storages¶

GET /workspace-storage/

List all workspace storage configurations for your organization.

Parameters

Name	In	Type
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`display_name`	string
`workspace_id`	UUID
`config_type`	string
`config`	object
`is_active`	boolean
`is_managed`	boolean
`region`	string
`health_status`	string
`last_health_check_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Get workspace storage¶

GET /workspace-storage/{storage_id}

Get workspace storage by ID.

Parameters

Name	In	Type	Required
`storage_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`display_name`	string
`workspace_id`	UUID
`config_type`	string
`config`	object
`is_active`	boolean
`is_managed`	boolean
`region`	string
`health_status`	string
`last_health_check_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Update workspace storage¶

PATCH /workspace-storage/{storage_id}

Update workspace storage configuration.

Parameters

Name	In	Type	Required
`storage_id`	path	UUID	Yes

Request body

Field	Type
`display_name`	string
`config`	object
`credentials`	object
`is_active`	boolean

Response

Field	Type
`id`	UUID
`display_name`	string
`workspace_id`	UUID
`config_type`	string
`config`	object
`is_active`	boolean
`is_managed`	boolean
`region`	string
`health_status`	string
`last_health_check_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Delete workspace storage¶

DELETE /workspace-storage/{storage_id}

Delete workspace storage.

Parameters

Name	In	Type	Required
`storage_id`	path	UUID	Yes

Response

The raw file content.

Get storage for workspace¶

GET /workspace-storage/workspace/{workspace_id}

Get storage configuration for a workspace (works for any depth).

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`display_name`	string
`workspace_id`	UUID
`config_type`	string
`config`	object
`is_active`	boolean
`is_managed`	boolean
`region`	string
`health_status`	string
`last_health_check_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Check storage health¶

POST /workspace-storage/{storage_id}/health-check

Run health check on workspace storage.

Parameters

Name	In	Type	Required
`storage_id`	path	UUID	Yes

Response

The raw file content.

What’s next?¶

API overview: authentication, worked examples, and error handling
Webhooks: get events pushed to your systems instead of polling
Service accounts: create the key an integration uses