搜索 File - Qoder

POST /api/v1/forward/files/search 必须携带 x-qoder-beta: search-2026-08-31。搜索条件均可选并放在 JSON Body 中，URL Query 中的同名搜索参数会被忽略；归属选择参数 identity_id 例外，只能通过 Query 传入。请求体必须是单个 JSON object，空条件使用 {}。

归属查询参数

参数	类型	必选	说明
`identity_id`	string	否	仅在操作 Identity 归属资源时使用；PAT 可通过 Query 显式传入，不传时为管理员视角；SAT 由凭证确定归属，任何 SAT 显式携带该参数（包括空值）返回 HTTP 400。放入 JSON Body 会作为未知字段返回 400。详见 Identity 归属。

搜索条件（JSON Body）

参数	类型	说明
`metadata`	object<string,string>	metadata 精确匹配条件，多个条件为 AND；最多 16 项。
`limit`	integer	分页大小，默认 20，范围 1～100。
`page`	string	上一页 `next_page` 返回的游标。
`name`	string	文件名模糊匹配（包含关系），不区分大小写，最长 255。
`scope_id`	string	资源 Scope ID，目前为 Session ID。

curl -X POST "https://api.qoder.com/api/v1/forward/files/search" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: search-2026-08-31" \
  -d '{"metadata":{"project":"demo"},"name":"report","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 中的资源字段与列出 File一致。 metadata key 长度为 1～64 个字符且不能全为空白，value 必须是最长 512 个字符的字符串。客户端必须原样重放 next_page，不得自行构造游标。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 Beta Header、请求体或搜索参数非法，SAT 显式携带 Query `identity_id`（含空值），或在 JSON Body 中传入 `identity_id`。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	管理员 Scope 发生 Owner mismatch，或下游服务拒绝访问。
404	`not_found_error`	PAT 指定的 Identity 不存在、已禁用、已删除或不属于当前调用方。
429	`rate_limit_error`	超过 Forward 或下游限流。
500/502/503	`api_error`	Forward 或依赖服务失败。

​归属查询参数

​搜索条件（JSON Body）

​响应

​错误码

归属查询参数

搜索条件（JSON Body）

响应

错误码