Workspace management

These endpoints manage workspace entries (projects) tracked by the server, and bind or unbind containers to a workspace.

GET /api/v1/workspaces

Get a paginated list of all workspaces (projects) known to the server.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	Page number (1-indexed). Default: 1
limit	query	integer	No	Items per page (max 200). Default: 50

Response

200

{
  "items": [
    {
      "id": "global",
      "worktree": "/home/user/projects/global",
      "vcs": "git",
      "name": "Global",
      "icon": {
        "url": "https://example.com/icon.png",
        "override": "G",
        "color": "#6366f1"
      },
      "commands": {
        "start": "npm install"
      },
      "time": {
        "created": 1700000000000,
        "updated": 1700000001000,
        "initialized": 1700000000500
      },
      "branches": [],
      "workspace": null,
      "panels": null,
      "programs": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}

SDK usage

const { items, meta } = await client.agent.workspace.workspacesList({
  page: 1,
  limit: 50,
});

GET /api/v1/workspaces/{workspaceID}

Retrieve detailed information about a specific workspace by its project ID.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace ID (24-char lowercase hex)

Response

200

{
  "id": "507f1f77bcf86cd799439011",
  "worktree": "/home/user/projects/hoody",
  "vcs": "git",
  "name": "Hoody",
  "icon": {
    "url": "https://example.com/icon.png",
    "override": "H",
    "color": "#22c55e"
  },
  "commands": {
    "start": "pnpm install"
  },
  "time": {
    "created": 1700000000000,
    "updated": 1700000001000,
    "initialized": 1700000000500
  },
  "branches": [],
  "workspace": null,
  "panels": null,
  "programs": null
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Workspace not found"
  }
}

SDK usage

const workspace = await client.agent.workspace.workspacesGet({
  workspaceID: "507f1f77bcf86cd799439011",
});

POST /api/v1/workspaces

Create a new workspace entry in workspace-state.

This endpoint takes no parameters.

Request body

Field	Type	Required	Description
worktree	string	Yes	Absolute path of the git worktree
name	string	No	Display name for the workspace
color	string	No	Hex or CSS color used to render the workspace chip
visible	boolean	No	Whether the workspace appears in the sidebar
container	object	Yes	Container binding configuration

{
  "worktree": "/home/user/projects/hoody",
  "name": "Hoody",
  "color": "#22c55e",
  "visible": true
}

Response

200

{
  "id": "507f1f77bcf86cd799439011"
}

400

{
  "data": {},
  "errors": [
    {
      "path": "worktree",
      "message": "worktree is required"
    }
  ],
  "success": false
}

SDK usage

const { id } = await client.agent.workspace.workspacesCreate({
  worktree: "/home/user/projects/hoody",
  name: "Hoody",
});

PATCH /api/v1/workspaces/{workspaceID}

Update workspace properties such as name, icon, and commands.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace ID (24-char lowercase hex)

Request body

Field	Type	Required	Description
name	string	No	New display name for the workspace
icon	object	No	Icon override (url, override, color)
commands	object	No	Workspace commands (start is a startup script for new worktrees)

{
  "name": "Hoody (renamed)",
  "icon": {
    "override": "H",
    "color": "#0ea5e9"
  },
  "commands": {
    "start": "pnpm install && pnpm dev"
  }
}

Response

200

{
  "id": "507f1f77bcf86cd799439011",
  "worktree": "/home/user/projects/hoody",
  "vcs": "git",
  "name": "Hoody (renamed)",
  "icon": {
    "url": "",
    "override": "H",
    "color": "#0ea5e9"
  },
  "commands": {
    "start": "pnpm install && pnpm dev"
  },
  "time": {
    "created": 1700000000000,
    "updated": 1700000002000,
    "initialized": 1700000000500
  },
  "branches": []
}

400

{
  "data": {},
  "errors": [
    {
      "path": "icon.color",
      "message": "Invalid color value"
    }
  ],
  "success": false
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Workspace not found"
  }
}

SDK usage

const updated = await client.agent.workspace.workspacesUpdate({
  workspaceID: "507f1f77bcf86cd799439011",
  name: "Hoody (renamed)",
});

DELETE /api/v1/workspaces/{workspaceID}

Remove a workspace entry from workspace-state.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace ID (24-char lowercase hex)

Response

200

{
  "ok": true
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Workspace not found"
  }
}

SDK usage

await client.agent.workspace.workspacesDelete({
  workspaceID: "507f1f77bcf86cd799439011",
});

Container binding

These endpoints attach a running container to a workspace entry, and remove the attachment.

Note

Binding a container does not create it. You must provision a container elsewhere and then record the binding against the workspace.

POST /api/v1/workspaces/{workspaceID}/container

Set the container binding for a workspace entry.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace ID (24-char lowercase hex)

Request body

Field	Type	Required	Description
containerId	string	Yes	Identifier of the container to bind
projectId	string	Yes	Container’s project identifier
serverNode	string	Yes	Node on which the container is running

{
  "containerId": "c-8a1b2c3d4e5f",
  "projectId": "p-001",
  "serverNode": "node-eu-west-1"
}

Response

200

{
  "ok": true
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Workspace not found"
  }
}

SDK usage

await client.agent.workspace.bind({
  workspaceID: "507f1f77bcf86cd799439011",
  containerId: "c-8a1b2c3d4e5f",
  projectId: "p-001",
  serverNode: "node-eu-west-1",
});

DELETE /api/v1/workspaces/{workspaceID}/container

Remove the container binding from a workspace entry.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace ID (24-char lowercase hex)

Response

200

{
  "ok": true
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Workspace not found"
  }
}

SDK usage

await client.agent.workspace.unbind({
  workspaceID: "507f1f77bcf86cd799439011",
});