Workspaces

Create, manage, and control development workspaces. Workspaces are interactive computing environments (e.g., Jupyter, VS Code, RStudio) provisioned within a project.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Workspace Object

{
  "id": "ws_ghi789",
  "name": "Training Environment",
  "description": "GPU-enabled workspace for model training",
  "status": "running",
  "environmentType": "jupyter",
  "image": "strongly/jupyter-gpu:latest",
  "resources": {
    "cpu": "4",
    "memory": "16Gi",
    "gpu": "1",
    "gpuType": "nvidia-a10g",
    "storage": "50Gi"
  },
  "organizationId": "org_xyz",
  "owner": {
    "id": "user_456",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "ownerId": "user_456",
  "url": "https://ws-ghi789.workspaces.strongly.ai",
  "projectId": "proj_abc123",
  "volumeIds": ["vol_def001", "vol_def002"],
  "createdAt": "2025-01-16T11:00:00Z",
  "updatedAt": "2025-02-01T08:00:00Z"
}

---

GET /api/v1/workspaces

List all workspaces accessible to the authenticated user.

Scope: workspaces:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by name or description
status	string	No	Filter by status: pending, running, stopped, failed, terminated
projectId	string	No	Filter by project ID
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 8,
  "limit": 20,
  "offset": 0,
  "workspaces": [
    {
      "id": "ws_ghi789",
      "name": "Training Environment",
      "description": "GPU-enabled workspace for model training",
      "status": "running",
      "environmentType": "jupyter",
      "image": "strongly/jupyter-gpu:latest",
      "organizationId": "org_xyz",
      "ownerId": "user_456",
      "url": "https://ws-ghi789.workspaces.strongly.ai",
      "projectId": "proj_abc123",
      "createdAt": "2025-01-16T11:00:00Z",
      "updatedAt": "2025-02-01T08:00:00Z"
    }
  ]
}

---

POST /api/v1/workspaces

Create a new workspace.

Scope: workspaces:write

Request Body

{
  "name": "Training Environment",
  "description": "GPU-enabled workspace for model training",
  "environmentType": "jupyter",
  "image": "strongly/jupyter-gpu:latest",
  "resources": {
    "cpu": "4",
    "memory": "16Gi",
    "gpu": "1",
    "gpuType": "nvidia-a10g",
    "storage": "50Gi"
  },
  "projectId": "proj_abc123"
}

Field	Type	Required	Description
name	string	Yes	Workspace name
description	string	Yes	Workspace description
environmentType	string	Yes	Environment type: jupyter, vscode, rstudio, custom
image	string	No	Container image to use (defaults to environment type default)
resources	object	No	Resource requests (cpu, memory, gpu, gpuType, storage)
projectId	string	No	Project to attach the workspace to

Response 201 Created

{
  "workspaceId": "ws_ghi789"
}

---

GET /api/v1/workspaces/:id

Get a single workspace by ID.

Scope: workspaces:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

Returns the full Workspace object.

---

PUT /api/v1/workspaces/:id

Update an existing workspace. Certain fields (e.g., resources) can only be updated while the workspace is stopped.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Request Body

{
  "name": "Updated Training Environment",
  "description": "Updated description",
  "resources": {
    "cpu": "8",
    "memory": "32Gi",
    "gpu": "2"
  }
}

Field	Type	Required	Description
name	string	No	Workspace name
description	string	No	Workspace description
image	string	No	Container image
resources	object	No	Resource requests (workspace must be stopped)

Response 200 OK

Returns the updated Workspace object.

---

DELETE /api/v1/workspaces/:id

Delete a workspace. The workspace must be stopped before deletion. This action is irreversible.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 204 No Content

---

POST /api/v1/workspaces/:id/start

Start a stopped workspace. Provisions the underlying compute resources and makes the workspace accessible.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "message": "Workspace starting",
  "workspaceId": "ws_ghi789",
  "status": "pending"
}

---

POST /api/v1/workspaces/:id/stop

Stop a running workspace. Releases compute resources while preserving workspace state.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "message": "Workspace stopping",
  "workspaceId": "ws_ghi789",
  "status": "stopped"
}

---

POST /api/v1/workspaces/:id/restart

Restart a running workspace. Equivalent to stop followed by start.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "message": "Workspace restarting",
  "workspaceId": "ws_ghi789",
  "status": "pending"
}

---

GET /api/v1/workspaces/:id/status

Get the current runtime status and health of a workspace.

Scope: workspaces:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "phase": "Running",
  "ready": true,
  "message": "Workspace is running and ready",
  "conditions": [
    {
      "type": "PodScheduled",
      "status": "True",
      "lastTransitionTime": "2025-02-01T08:00:00Z"
    },
    {
      "type": "Ready",
      "status": "True",
      "lastTransitionTime": "2025-02-01T08:01:30Z"
    }
  ]
}

---

GET /api/v1/workspaces/:id/metrics

Get real-time resource utilization metrics for a running workspace.

Scope: workspaces:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "cpuUsage": "2.4",
  "memoryUsage": "12.8Gi",
  "gpuUsage": "85%",
  "diskUsage": "32.1Gi"
}

---

GET /api/v1/workspaces/:id/logs

Retrieve logs for a workspace. Supports different log types for build, deploy, and runtime phases.

Scope: workspaces:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Query Parameters

Parameter	Type	Required	Description
type	string	No	Log type: build, deploy, pod (default: pod)

Response 200 OK

{
  "workspaceId": "ws_ghi789",
  "logType": "pod",
  "logs": "2025-02-01T08:01:30Z Starting Jupyter server...\n2025-02-01T08:01:32Z Jupyter server is running at https://0.0.0.0:8888\n"
}

---

POST /api/v1/workspaces/:id/sync

Sync workspace files to the attached volume. Ensures that any in-progress work is persisted to storage.

Scope: workspaces:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Workspace ID

Response 200 OK

{
  "message": "Workspace sync initiated",
  "workspaceId": "ws_ghi789"
}