# List workspaces

Workspaces (billing accounts), their brands, and the agents in each brand that this token can reach.

|  |  |
| --- | --- |
| REST | `GET /api/v1/workspaces` |
| MCP tool | `list_workspaces` |
| Classification | **Read** (changes nothing) |
| Scope | Any valid token |
| Minimum role on the agent | any member |
| Confirmation | Not needed |
| Retry safety | Safe to retry with the same input |
| Success status | 200 |

## What it does

Workspaces (billing accounts), their brands, and the agents in each brand that this token can reach.

## Side effects

None. It only reads.

## Inputs

No inputs.

## Example

REST:

```bash
curl "https://covo.lanaai.io/api/v1/workspaces" \
  -H "Authorization: Bearer $COVO_TOKEN"
```

MCP (POST /mcp):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_workspaces",
    "arguments": {}
  }
}
```

## Response

Returns an object with `workspaces`. This is a real response, shortened to two items per list.

200 response:

```json
{
  "workspaces": [
    {
      "id": "df39921a-9546-4e6d-9241-90ee65891dbf",
      "name": "Avery Quinn",
      "plan": "Pro",
      "brands": [
        {
          "id": "ae435f18-5eab-4afe-abff-eb88f1e3ffd3",
          "name": "Avery Quinn",
          "agents": [
            {
              "id": "agt_4edc89bb2964",
              "name": "Avery Quinn's Concierge",
              "represents": "Avery Quinn",
              "slug": "avery",
              "status": "draft",
              "role": "owner",
              "workspace_id": "df39921a-9546-4e6d-9241-90ee65891dbf",
              "brand_id": "ae435f18-5eab-4afe-abff-eb88f1e3ffd3",
              "url": "https://covo.lanaai.io/avery"
            }
          ]
        }
      ]
    }
  ]
}
```

Over MCP the same object comes back as the tool result, in `structuredContent` and as JSON text.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect. |
| 403 | `account_suspended` | The account that owns the token is paused. |
| 400 | `bad_request` | An input is invalid; `field` names it. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |