> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 列出 Vaults

> 获取当前账户下的 Vault 列表，支持游标分页和名称搜索。

`GET /api/v1/cloud/vaults`

获取当前账户下的 Vault 列表，支持游标分页和名称搜索。默认不返回已归档 Vault。

## 请求头

| 头部              | 必选 | 说明             |
| --------------- | -- | -------------- |
| `Authorization` | 是  | `Bearer <PAT>` |

## 查询参数

| 参数                 | 类型      | 必选 | 说明                                                            |
| ------------------ | ------- | -- | ------------------------------------------------------------- |
| `limit`            | integer | 否  | 每页返回数量上限。默认 20，范围 1-100。超过 100 返回 `400 invalid_request_error` |
| `page`             | string  | 否  | Claude 风格的向后翻页游标，等价于 `after_id`；与 `before_id`、`after_id` 互斥   |
| `after_id`         | string  | 否  | 游标分页：返回此 ID 之后的记录。与 `page`、`before_id` 互斥                     |
| `before_id`        | string  | 否  | 游标分页：返回此 ID 之前的记录。与 `page`、`after_id` 互斥                      |
| `include_archived` | boolean | 否  | 设为 `true` 时包含已归档 Vault                                        |
| `name`             | string  | 否  | 按显示名称搜索 Vault                                                 |

完整分页规范详见 [分页](/zh/cloud-agents/api/conventions/pagination)。

## 示例请求

```bash theme={null}
# 获取所有 Vault
curl -X GET "https://api.qoder.com/api/v1/cloud/vaults" \
  -H "Authorization: Bearer $QODER_PAT"

# 分页获取
curl -X GET "https://api.qoder.com/api/v1/cloud/vaults?limit=2" \
  -H "Authorization: Bearer $QODER_PAT"

# 按名称搜索，并包含已归档 Vault
curl -X GET "https://api.qoder.com/api/v1/cloud/vaults?name=my-mcp&include_archived=true" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "vault_019e3bb940277f0db05ab74291acf6ef",
      "type": "vault",
      "display_name": "my-mcp-vault",
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-18T15:34:16.874877Z",
      "updated_at": "2026-05-18T15:34:16.874877Z"
    }
  ],
  "next_page": null,
  "first_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "last_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "has_more": false
}
```

空列表响应：

```json theme={null}
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 响应字段

| 字段          | 类型             | 说明                                                         |
| ----------- | -------------- | ---------------------------------------------------------- |
| `data`      | array          | [Vault 对象](/zh/cloud-agents/api/vaults/schemas#vault-对象)数组 |
| `next_page` | string \| null | 下一页向后游标；`has_more` 为 `true` 时传给 `page`                     |
| `first_id`  | string \| null | 当前页第一条记录 ID                                                |
| `last_id`   | string \| null | 当前页最后一条记录 ID（用于游标分页）                                       |
| `has_more`  | boolean        | 是否还有更多记录                                                   |

## 错误码

| HTTP | type                    | 触发条件                                             |
| ---- | ----------------------- | ------------------------------------------------ |
| 400  | `invalid_request_error` | `limit` 非法，或同时传入多个 `page`、`before_id`、`after_id` |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                                       |

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="Vaults" icon="key" href="/zh/cloud-agents/vaults">
    安全地存储凭据并注入到 Agent Session。
  </Card>
</CardGroup>