Workspaces API

Workspaces represent a project directory. Each workspace has its own set of agents, roles, and configuration.

List workspaces

GET /api/workspaces

Returns all workspaces.

Response: 200 array of Workspace objects.

[
  {
    "id": "abc123",
    "name": "my-project",
    "cwd": "/home/user/projects/my-project",
    "color": "#c8ee44",
    "agents": ["code", "review"]
  }
]

---

Create workspace

POST /api/workspaces

Request body:

Field	Type	Required	Description
name	string	yes	Workspace display name
cwd	string	yes	Absolute path to the project directory
color	string	no	Hex color for the UI (default #c8ee44)

Response: 201 with workspace data including detected roles, agents, and existing sessions.

---

Get workspace

GET /api/workspaces/:id

Returns the full workspace data: workspace metadata, detected roles, active agents, and existing SDK sessions.

Response:

{
  "workspace": { "id": "...", "name": "...", "cwd": "..." },
  "availableRoles": ["code", "review", "architect"],
  "agents": [ ... ],
  "sessions": [ ... ]
}

---

Get workspace agents

GET /api/workspaces/:id/agents

Returns active and closed agents for the workspace. Agent logs are truncated to the last 50 entries for payload size; use GET /api/agents/:id/log for the full log.

Response:

{
  "workspace": { ... },
  "agents": [ ... ],
  "history": [ ... ]
}

---

Get workspace roles

GET /api/workspaces/:id/roles

Detects available agent roles from the project directory (based on CLAUDE.md and .claude/ files).

Response:

{
  "availableRoles": ["code", "review", "architect"],
  "roles": [
    { "name": "code", "source": "..." }
  ]
}

---

Update workspace

PATCH /api/workspaces/:id

Request body (all optional):

Field	Type	Description
name	string	Display name
cwd	string	Project directory
color	string	Hex color
orchestratorRole	string	Role name designated as orchestrator

Response: 200 with the updated workspace.

---

Delete workspace

DELETE /api/workspaces/:id

Deletes the workspace and removes all its agents.

Response: 200 { ok: true }

---

Reset workspace

POST /api/workspaces/:id/reset

Removes all agents from the workspace and resets state. Broadcasts a workspace_reset WebSocket event.

Response: 200 { ok: true }

---

Get role template

GET /api/workspaces/:id/role-template/:role

Returns the saved template for a role, or an empty object if none exists.

Response:

{
  "model": "claude-sonnet-4-20250514",
  "isOrchestrator": false,
  "canSpawnSubagents": true,
  "defaultTask": "Read CLAUDE.md and report ready.",
  "effort": "medium"
}

---

Update role template

PUT /api/workspaces/:id/role-template/:role

Sets default configuration for agents spawned with this role.

Request body:

Field	Type	Description
model	string	Default model for the role
isOrchestrator	boolean	Spawn as orchestrator
canSpawnSubagents	boolean	Allow SDK Agent tool
defaultTask	string	Default initial task
effort	string	Default effort level

Response: 200 with the saved template.

---

Serve attachment

GET /api/workspaces/:id/attachments/:filename

Serves a previously uploaded attachment file. Returns the file with the appropriate Content-Type header. Responses are cached with Cache-Control: public, max-age=31536000, immutable.

Supported file types: PNG, JPEG, GIF, WebP, PDF, TXT, Markdown, CSV.

Response: 200 with file contents, or 404 if not found.