Skip to main content
Creates a new workspace in the specified project. The workspace will be provisioned with the given hardware configuration or your default settings.

​
Authentication

Requires a valid Bearer token.

​
Path Parameters

​
id
string
required
Project ID (UUID).

​
Request Body

​
hardware
object
Hardware configuration. Uses your default hardware settings if omitted.
​
keep_active
boolean
Whether the workspace should stay running when idle. Default: false.
{
  "hardware": {
    "cpu_kind": "shared",
    "cpus": 2,
    "memory_mb": 2048,
    "volume_size_gb": 10,
    "gpu_kind": null
  },
  "keep_active": false
}

​
Response

Returns the created workspace object.
​
id
string
required
Unique workspace identifier (UUID).
​
project_id
string
required
ID of the parent project.
​
status
string
required
Initial status, typically "creating".
​
hardware
object
required
Hardware configuration.
​
keep_active
boolean
required
Whether the workspace stays running when idle.
​
machine_id
string
Machine ID (null until provisioned).
​
private_ip
string
Private IP address (null until provisioned).
​
git_ref
string
Current git reference.
​
preview_token
string
Token for accessing workspace preview URLs.
​
error_message
string
Error details if provisioning fails.
​
created_at
string
required
ISO 8601 timestamp.
​
updated_at
string
required
ISO 8601 timestamp.
{
  "id": "b2c3d4e5-6789-01ab-cdef-234567890abc",
  "project_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "creating",
  "hardware": {
    "cpu_kind": "shared",
    "cpus": 2,
    "memory_mb": 2048,
    "volume_size_gb": 10,
    "gpu_kind": null
  },
  "keep_active": false,
  "machine_id": null,
  "private_ip": null,
  "git_ref": null,
  "preview_token": "ptk_abc123",
  "error_message": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

​
Errors

StatusDescription
400Bad Request — invalid hardware configuration
401Unauthorized — missing or invalid token
404Not Found — project does not exist or you do not have access