搜索 Vault - Qoder CN

POST /api/v1/forward/vaults/search 支持 PAT、Admin SAT 和 Identity SAT，必须携带 x-qoder-beta: search-2026-08-31。搜索条件均放在 JSON Body 中；URL Query 中的搜索参数会被忽略。请求体必须是单个 JSON object，空条件使用 {}。

查询参数

参数	类型	必选	说明
`identity_id`	string	否	仅在操作 Identity 归属资源时使用，非必填；PAT 场景可显式传入，未传时为管理员视角；SAT 场景请签发 Identity 维度凭证且不要显式携带该参数，否则返回 HTTP 400（详见 Identity 归属）。

PAT 不传 identity_id 时搜索当前账户或 Workspace 的 Vault，传入时只搜索该 Identity；Admin SAT 只搜索 Workspace，Identity SAT 只搜索令牌绑定 Identity。不同 Scope 的资源不会出现在结果中。

请求体

参数	类型	说明
`metadata`	object<string,string>	metadata 精确匹配条件，多个条件为 AND；最多 16 项。
`limit`	integer	分页大小，默认 20，范围 1～100。
`page`	string	上一页 `next_page` 返回的游标。
`include_archived`	boolean	是否包含 CAS 与 Forward 均可见的已归档 Vault，默认 `false`。
`name`	string	显示名称模糊匹配（包含关系），不区分大小写，最长 255。

curl -X POST "https://api.qoder.com.cn/api/v1/forward/vaults/search" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: search-2026-08-31" \
  -d '{"metadata":{"team":"core"},"name":"production","limit":20}'

响应

字段	类型	说明
`data`	array	当前页 Forward 可见资源列表，资源字段见对应 List 接口。
`first_id`	string \| null	当前页第一条资源 ID。
`last_id`	string \| null	当前页最后一条资源 ID。
`has_more`	boolean	是否已确认存在下一页 Forward 可见资源。
`next_page`	string \| null	下一页游标，无下一页时为 `null`。

{
  "data": [],
  "first_id": null,
  "has_more": false,
  "last_id": null,
  "next_page": null
}

data 中的资源字段与列出 Vault一致。 metadata key 长度为 1～64 个字符且不能全为空白，value 必须是最长 512 个字符的字符串。客户端必须原样重放 next_page，不得自行构造游标。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 Beta Header、请求体或搜索参数非法；或 SAT 显式携带 `identity_id`。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	当前调用方无权访问资源。
404	`not_found_error`	PAT 指定的 `identity_id` 无效、已禁用、已删除或不属于当前调用方。
429	`rate_limit_error`	超过 Forward 或下游限流。
500/502/503	`api_error`	Forward 或依赖服务失败。

​查询参数

​请求体

​响应

​错误码

查询参数

请求体

响应

错误码