Appearance
Workspace API
REST API for managing GhostScience workspaces: persistent notebook-style environments with ordered cells, branching, and optional clean room linking.
Base path: /api/workspace
All endpoints require Bearer token authentication via the standard GhostAI auth middleware.
Endpoints
Create a Workspace
POST /api/workspaceRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Workspace name (1-256 chars) |
clean_room_mode | boolean | no | Enable clean room governance (default false) |
clean_room_id | string | no | Link to an existing clean room |
participating_org_ids | string[] | no | Organization IDs for clean room mode |
Response (201): Full WorkspaceDetail including empty cells array.
json
{
"id": "ws-abc123",
"name": "Drug interaction PK/PD model",
"owner_user_id": "user-1",
"organization_id": "org-1",
"branch": "main",
"clean_room_mode": false,
"clean_room_id": null,
"participating_org_ids": [],
"created_at": "2026-03-29T12:00:00Z",
"updated_at": "2026-03-29T12:00:00Z",
"cells": []
}List Workspaces
GET /api/workspaceReturns workspaces owned by the caller or belonging to the caller's organization, ordered by updated_at descending.
Response: Array of WorkspaceRecord objects.
Get a Workspace
GET /api/workspace/{workspace_id}Returns the workspace with all cells ordered by execution_order.
Response: WorkspaceDetail with nested cells array.
Upsert a Cell
PUT /api/workspace/{workspace_id}/cellCreate or update a cell. If cell_id matches an existing cell, it is updated; otherwise a new cell is created.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
cell_id | string | no | Cell ID (auto-generated if omitted) |
cell_type | string | no | computation or markdown (default computation) |
content | string | no | Cell content (code or markdown) |
output | object | no | Pre-set output (merged with existing on update) |
execution_order | integer | no | Position in the cell list |
depends_on | string[] | no | IDs of upstream cells |
is_stale | boolean | no | Whether the cell needs re-execution |
Response: The saved WorkspaceCellModel.
json
{
"id": "cell-1",
"workspace_id": "ws-abc123",
"cell_type": "computation",
"content": "import sympy as sp\nsp.integrate(sp.Symbol('x')**2, sp.Symbol('x'))",
"output": {},
"execution_order": 0,
"depends_on": [],
"is_stale": false,
"created_at": "2026-03-29T12:00:00Z",
"updated_at": "2026-03-29T12:00:00Z"
}Run a Cell
POST /api/workspace/{workspace_id}/cell/{cell_id}/runExecute a computation cell in the PhD sandbox. Markdown cells are skipped with {"skipped": true}.
Response: Updated cell with execution output:
json
{
"id": "cell-1",
"output": {
"stdout": "x**3/3",
"stderr": "",
"exit_code": 0,
"execution_time_ms": 1234,
"backend": "docker"
},
"is_stale": false
}Create a Branch
POST /api/workspace/{workspace_id}/branchRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
branch_name | string | yes | Branch name (1-128 chars) |
parent_branch | string | no | Parent branch (default null) |
Response (201): BranchRecord.
json
{
"id": "br-xyz",
"workspace_id": "ws-abc123",
"branch_name": "experiment-adam-optimizer",
"parent_branch": "main",
"created_at": "2026-03-29T12:00:00Z"
}Error (409): Branch name already exists.
List Branches
GET /api/workspace/{workspace_id}/branchesResponse: Array of BranchRecord objects ordered by created_at.
Access Control
- Owner: Full access to the workspace
- Same organization: Users in the same org can view and edit
- Cross-org (clean room): All participating orgs can access when
clean_room_modeis enabled
Related
- Workspaces Feature -- feature overview
- PhD API -- scientific computation endpoints
- Clean Room API -- federated computation endpoints
- SDK Reference -- Python client library