Workspace Management

Overview

Workspaces are containers that organize agents, tasks, notes, and codebases. Each workspace represents a project or collection of related work.

Workspace Status

Status	Description
`active`	Workspace is currently active
`archived`	Workspace has been archived

List Workspaces

curl http://localhost:3000/api/workspaces

Endpoint

GET /api/workspaces

GET

List all workspaces

Query Parameters

status

string

Filter by status: active or archived

Response

workspaces

array

required

Array of workspace objects

Workspace Object

string

required

Unique workspace identifier

title

string

required

Workspace title

repoPath

string

Path to associated repository

branch

string

Git branch name

status

string

required

Workspace status: active or archived

metadata

object

required

Additional metadata as key-value pairs

createdAt

string

required

ISO 8601 timestamp of creation

updatedAt

string

required

ISO 8601 timestamp of last update

Response Example

{
  "workspaces": [
    {
      "id": "workspace-123",
      "title": "My Project",
      "repoPath": "/path/to/repo",
      "branch": "main",
      "status": "active",
      "metadata": {
        "description": "Main project workspace"
      },
      "createdAt": "2026-03-03T10:00:00.000Z",
      "updatedAt": "2026-03-03T10:00:00.000Z"
    }
  ]
}

Create Workspace

curl -X POST http://localhost:3000/api/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Project",
    "repoPath": "/path/to/repo",
    "branch": "main",
    "metadata": {"description": "Main workspace"}
  }'

Endpoint

POST /api/workspaces

POST

Create a new workspace

Request Body

title

string

required

Workspace title

repoPath

string

Path to associated repository

branch

string

Git branch name

metadata

object

Additional metadata as key-value pairs

Response

workspace

object

required

The created workspace object

Response Example

{
  "workspace": {
    "id": "workspace-123",
    "title": "My Project",
    "repoPath": "/path/to/repo",
    "branch": "main",
    "status": "active",
    "metadata": {
      "description": "Main workspace"
    },
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  }
}

Get Workspace by ID

curl http://localhost:3000/api/workspaces/workspace-123

Endpoint

GET /api/workspaces/{id}

GET

Get a single workspace with its codebases

Path Parameters

string

required

The workspace ID

Response

workspace

object

required

The workspace object

codebases

array

required

Array of codebase objects associated with this workspace

Response Example

{
  "workspace": {
    "id": "workspace-123",
    "title": "My Project",
    "status": "active",
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  },
  "codebases": [
    {
      "id": "codebase-456",
      "name": "main-repo",
      "path": "/path/to/repo",
      "sourceType": "local"
    }
  ]
}

Status Codes

Status Code	Description
`200`	Success
`404`	Workspace not found

Update Workspace

curl -X PATCH http://localhost:3000/api/workspaces/workspace-123 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Project Name",
    "repoPath": "/new/path",
    "branch": "develop",
    "status": "active",
    "metadata": {"version": "2.0"}
  }'

Endpoint

PATCH /api/workspaces/{id}

PATCH

Update workspace properties

Path Parameters

string

required

The workspace ID

Request Body

All fields are optional. Only provided fields will be updated.

title

string

New workspace title

repoPath

string

New repository path

branch

string

New branch name

status

string

New status: active or archived

metadata

object

Metadata to merge with existing metadata

Response

workspace

object

required

The updated workspace object

Response Example

{
  "workspace": {
    "id": "workspace-123",
    "title": "Updated Project Name",
    "repoPath": "/new/path",
    "branch": "develop",
    "status": "active",
    "metadata": {
      "version": "2.0"
    },
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T11:00:00.000Z"
  }
}

Delete Workspace

curl -X DELETE http://localhost:3000/api/workspaces/workspace-123

Endpoint

DELETE /api/workspaces/{id}

DELETE

Delete a workspace

Path Parameters

string

required

The workspace ID to delete

Response

deleted

boolean

required

Always true when successful

Response Example

{
  "deleted": true
}

Archive Workspace

curl -X POST http://localhost:3000/api/workspaces/workspace-123/archive \
  -H "Content-Type: application/json" \
  -d '{"archive": true}'

Endpoint

POST /api/workspaces/{id}/archive

POST

Archive or unarchive a workspace

Path Parameters

string

required

The workspace ID

Request Body

Response

workspace

object

required

The updated workspace with new status

Response Example

{
  "workspace": {
    "id": "workspace-123",
    "title": "My Project",
    "status": "archived",
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T12:00:00.000Z"
  }
}

Codebase Source Types

Source Type	Description
`local`	Local filesystem codebase
`github`	GitHub repository codebase

Error Responses

400 Bad Request

{
  "error": "title is required"
}

404 Not Found

{
  "error": "Workspace not found"
}

REST API

MCP Tools

ACP

A2A

​Overview

​Workspace Status

​List Workspaces

​Endpoint

​Query Parameters

​Response

​Workspace Object

​Response Example

​Create Workspace

​Endpoint

​Request Body

​Response

​Response Example

​Get Workspace by ID

​Endpoint

​Path Parameters

​Response

​Response Example

​Status Codes

​Update Workspace

​Endpoint

​Path Parameters

​Request Body

​Response

​Response Example

​Delete Workspace

​Endpoint

​Path Parameters

​Response

​Response Example

​Archive Workspace

​Endpoint

​Path Parameters

​Request Body

​Response

​Response Example

​Codebase Source Types

​Error Responses

​400 Bad Request

​404 Not Found

Build docs developers (and LLMs) love

Overview

Workspace Status

List Workspaces

Endpoint

Query Parameters

Response

Workspace Object

Response Example

Create Workspace

Endpoint

Request Body

Response

Response Example

Get Workspace by ID

Endpoint

Path Parameters

Response

Response Example

Status Codes

Update Workspace

Endpoint

Path Parameters

Request Body

Response

Response Example

Delete Workspace

Endpoint

Path Parameters

Response

Response Example

Archive Workspace

Endpoint

Path Parameters

Request Body

Response

Response Example

Codebase Source Types

Error Responses

400 Bad Request

404 Not Found