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

Note

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

Warning

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
    }
  ]
}