# Agent: Workspace

**Page:** api/agent/workspace

[Download Raw Markdown](./api/agent/workspace.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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



```json
{
  "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

```ts
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



```json
{
  "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
}
```


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



#### SDK usage

```ts
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 |

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

#### Response



```json
{
  "id": "507f1f77bcf86cd799439011"
}
```


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



#### SDK usage

```ts
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) |

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

#### Response



```json
{
  "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": []
}
```


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


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



#### SDK usage

```ts
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



```json
{
  "ok": true
}
```


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



#### SDK usage

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

## Container binding

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


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 |

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

#### Response



```json
{
  "ok": true
}
```


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



#### SDK usage

```ts
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



```json
{
  "ok": true
}
```


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



#### SDK usage

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