Skip to content

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/workspace

Request Body

FieldTypeRequiredDescription
namestringyesWorkspace name (1-256 chars)
clean_room_modebooleannoEnable clean room governance (default false)
clean_room_idstringnoLink to an existing clean room
participating_org_idsstring[]noOrganization 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/workspace

Returns 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}/cell

Create or update a cell. If cell_id matches an existing cell, it is updated; otherwise a new cell is created.

Request Body

FieldTypeRequiredDescription
cell_idstringnoCell ID (auto-generated if omitted)
cell_typestringnocomputation or markdown (default computation)
contentstringnoCell content (code or markdown)
outputobjectnoPre-set output (merged with existing on update)
execution_orderintegernoPosition in the cell list
depends_onstring[]noIDs of upstream cells
is_stalebooleannoWhether 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}/run

Execute 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}/branch

Request Body

FieldTypeRequiredDescription
branch_namestringyesBranch name (1-128 chars)
parent_branchstringnoParent 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}/branches

Response: 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_mode is enabled

SOC 2 Type II Certified | BAA Available | HIPAA-Ready