Workspaces
Workspaces are isolated environments within your organization. Each workspace has its own devices, sites, customers, and API keys — making them ideal for separating production, staging, and partner environments.
Workspace object
{
"id": "ws_abc123def456",
"name": "Production",
"organizationId": "org_789xyz",
"deletionProtection": true,
"createdAt": "2025-01-15T00:00:00.000Z",
"updatedAt": "2025-01-15T00:00:00.000Z"
}| Field | Type | Description |
|---|---|---|
id | string | Unique workspace identifier |
name | string | Human-readable name |
organizationId | string | Parent organization ID |
deletionProtection | boolean | Whether the workspace is protected from deletion and clearing |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 last update timestamp |
Deletion protection is enabled by default when a workspace is created. This prevents accidental data loss. Use PUT /v1/workspaces/:id/protection to disable it when needed.
List workspaces
GET /v1/workspaces
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number (1–1000) |
perPage | integer | 20 | Items per page (1–100) |
Response: 200 OK
{
"data": [
{
"id": "ws_abc123def456",
"name": "Production",
"organizationId": "org_789xyz",
"deletionProtection": true,
"createdAt": "2025-01-15T00:00:00.000Z",
"updatedAt": "2025-01-15T00:00:00.000Z"
}
],
"meta": {
"total": 3,
"page": 1,
"perPage": 20
}
}Get workspace
GET /v1/workspaces/:id
| Parameter | Type | Description |
|---|---|---|
id | string | Workspace ID |
Response: 200 OK — Returns the workspace object.
Create workspace
POST /v1/workspaces
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Workspace name (min 1 character) |
{
"name": "Staging"
}Response: 201 Created — Returns the created workspace object with deletionProtection: true.
Update workspace
PATCH /v1/workspaces/:id
| Parameter | Type | Description |
|---|---|---|
id | string | Workspace ID |
Request body:
| Field | Type | Description |
|---|---|---|
name | string | New workspace name (min 1 character) |
{
"name": "Production Environment"
}Response: 200 OK — Returns the updated workspace object.
Set workspace protection
Enable or disable deletion protection. When enabled, the workspace cannot be deleted or cleared until protection is turned off.
PUT /v1/workspaces/:id/protection
| Parameter | Type | Description |
|---|---|---|
id | string | Workspace ID |
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
deletionProtection | boolean | Yes | true to enable, false to disable |
{
"deletionProtection": false
}Response: 200 OK — Returns the updated workspace object.
Clear workspace
Remove all entities (devices, sites, customers, etc.) from a workspace. The workspace itself is preserved.
POST /v1/workspaces/:id/clear
This is a destructive operation. All devices, sites, and customers in the workspace will be permanently deleted. This action is subject to the destructive rate limit (10 requests/minute).
If deletion protection is enabled, the request will fail with:
{
"message": "Cannot clear workspace: deletionProtection is enabled. Disable deletionProtection first."
}Deletion protection is enabled by default. Use PUT /v1/workspaces/:id/protection to disable it before clearing.
| Parameter | Type | Description |
|---|---|---|
id | string | Workspace ID |
Response: 200 OK
{
"success": true,
"message": "Workspace cleared successfully",
"totalDeleted": 128,
"results": [
{
"operation": "devices",
"success": true,
"deletedCount": 42,
"error": null
},
{
"operation": "sites",
"success": true,
"deletedCount": 10,
"error": null
},
{
"operation": "customers",
"success": true,
"deletedCount": 76,
"error": null
}
]
}