列出文件树
接口说明
浏览知识库当前可读取的文件和目录。
接口信息
| 字段 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /openapi/v2/knowledge-bases/{knowledgeBaseId}/tree |
| Operation ID | listKnowledgeBaseTree |
| 鉴权 | Bearer OpenAPI key |
入参
| 名称 | 位置 | 必填 | 类型 | 示例 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | knowledge-base-11111111-1111-4111-8111-111111111111 | 知识库 API 返回的知识库标识。 |
parentPath | query | 否 | string | pages | 要浏览的目录路径；使用 root 浏览知识库根目录。接口拒绝上级路径跳转、文件路径和存储路径。 |
entryType | query | 否 | file | directory | file | 可选的文件树节点类型筛选。 |
limit | query | 否 | integer | 50 | 最多返回的记录数量。部署环境可能采用更低的上限。 |
cursor | query | 否 | string | cursor_123 | 当前接口返回的下一页分页标记。 |
请求体
这个接口没有请求体。
请求示例
bash
curl -X GET "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/tree?parentPath=pages&entryType=file&limit=50" \
-H "Authorization: Bearer <openapi-key>"成功响应
200
返回所选上级目录下当前可读取的直属文件和目录分页。
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
activeContentRevision | 是 | object | 当前可读取知识库内容的修订号。 |
items | 是 | array<GeneratedTreeEntry> | 当前分页中的记录。 |
nextCursor | 是 | string | null | 当前接口返回的分页标记。只能在接口和可读取知识库版本不变时继续使用；被拒绝时请移除 cursor 并从第一页重新读取。 |
成功响应示例
json
{
"activeContentRevision": 1,
"items": [
{
"activeContentRevision": 1,
"id": "tree-file-11111111111111111111111111111111",
"fileId": "source-file-11111111-1111-4111-8111-111111111111",
"sourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
"directoryId": null,
"parentPath": "pages",
"name": "guide.md",
"path": "pages/guide.md",
"sortKey": "1:guide.md",
"entryType": "file",
"fileKind": "page",
"directEntryCount": 0,
"directDirectoryCount": 0,
"directFileCount": 0,
"descendantFileCount": 0,
"resourceRevision": 1,
"deletable": true,
"contentAvailable": true,
"readActions": {
"fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111",
"fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/content",
"fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fguide.md",
"relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/related",
"graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111",
"sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111"
}
}
],
"nextCursor": null
}错误码
下表列出这个接口已声明的全部错误响应。
| HTTP 状态 | 错误码 | 说明 |
|---|---|---|
| 401 | UNAUTHORIZED | Bearer API key 缺失、格式错误、未知、已撤销或已删除。 |
| 404 | NOT_FOUND | 请求的资源不存在。 |
| 422 | VALIDATION_ERROR | 请求未通过校验。 |
| 429 | RATE_LIMITED | 请求超过当前配置的速率限制。 |
| 500 | INTERNAL_ERROR | API 遇到内部错误。 |
| 503 | DATABASE_REPOSITORY_UNAVAILABLE | 当前接口所需的数据暂时不可用。 |