# List workspaces

List the workspaces that the current identity can access. Results can be filtered by name.

```text
GET https://moi.matrixorigin.cn/newmoi/workspaces
```

## Before you call this API

Prepare a personal access token.

The following example uses:

- `$AI_STUDIO_API_KEY`: Your personal access token, passed in the `X-API-Key` header.
- `$WORKSPACE_NAME`: An optional workspace-name filter, passed through the `name` query parameter.

## Request example

```bash
curl --get "https://moi.matrixorigin.cn/newmoi/workspaces" \
  --data-urlencode "name=$WORKSPACE_NAME" \
  -H "X-API-Key: $AI_STUDIO_API_KEY"
```

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Filters results by workspace name. |

## Successful response

On success, the API returns `200`. `data.workspaces` contains the workspaces that the current identity can access. If no workspace matches, it is an empty array.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspaces": [
      {
        "id": "ws_01",
        "name": "Analytics workspace",
        "status": "active",
        "owner_id": "user_01",
        "created_at": "2026-08-01T09:00:00Z",
        "access_status": "active",
        "invitation_id": ""
      }
    ],
    "total": 1
  }
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.workspaces` | array | Workspace list. It is an empty array when there are no matches. |
| `data.workspaces[].id` | string | Workspace ID. |
| `data.workspaces[].name` | string | Workspace name. |
| `data.workspaces[].status` | string | Current workspace status. |
| `data.workspaces[].owner_id` | string | User ID of the workspace owner. |
| `data.workspaces[].created_at` | string | Time when the workspace was created. |
| `data.workspaces[].access_status` | string | The current identity's access status for the workspace. |
| `data.workspaces[].invitation_id` | string | Invitation ID for the current identity; an empty string if there is no invitation. |
| `data.total` | integer | Number of returned workspaces. |

In field paths, `[]` denotes each item in an array. For example, `data.workspaces[].id` is the `id` field of each item in the `data.workspaces` array.

## Error response

```json
{
  "code": "ErrWorkspaceListFailed",
  "msg": "Failed to list workspaces",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status
  - Error code
  - Common cause
  - Recommended action
* - `401`
  - `Unauthorized`
  - Credentials are missing or invalid.
  - Check the personal access token.
* - `403`
  - `ErrUserNotSynced` or `PERMISSION_DENIED`
  - The current identity has not been synchronized or cannot access workspaces.
  - Complete account synchronization, or ask an administrator for access before retrying.
* - `400`
  - `INVALID_ARGUMENT`
  - The query parameter is invalid.
  - Check the `name` parameter and retry.
* - `503`
  - `UNAVAILABLE`
  - A dependent service is temporarily unavailable.
  - Retry later.
* - `500`
  - `ErrWorkspaceListFailed`
  - The service could not list workspaces.
  - Record the request time and error message, then retry.
```