列出已上传文件
接口说明
分页读取知识库中已经上传的 Markdown 文件及其处理状态。
接口信息
| 字段 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files |
| Operation ID | listKnowledgeBaseSourceFiles |
| 鉴权 | Bearer OpenAPI key |
入参
| 名称 | 位置 | 必填 | 类型 | 示例 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | knowledge-base-11111111-1111-4111-8111-111111111111 | 知识库 API 返回的知识库标识。 |
limit | query | 否 | integer | 50 | 最多返回的记录数量。部署环境可能采用更低的上限。 |
cursor | query | 否 | string | cursor_123 | 当前接口返回的下一页分页标记。 |
directoryId | query | 否 | string | directory-handbook | 上级上传目录标识。知识库根目录中的文件使用 root。 |
pathQuery | query | 否 | string | handbook/guide | 按已上传文件路径进行不区分大小写的模糊筛选。 |
sourceFileIdPrefix | query | 否 | string | source-file-11111111 | 按已上传文件 ID 前缀筛选。 |
state | query | 否 | waiting | processing | available | error | deleting | available | 当前处理状态。 |
blockingWorkKind | query | 否 | prepare | first_layer | content_projection | graphrag | relation_reconcile | knowledge_projection | activate | cleanup | activate | 按当前阻止文档变为可用的处理步骤筛选。 |
generatedOutputStatus | query | 否 | unavailable | previous_available | current_available | current_available | 生成结果当前是否可以读取。 |
请求体
这个接口没有请求体。
请求示例
bash
curl -X GET "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files?limit=50&directoryId=directory-handbook" \
-H "Authorization: Bearer <openapi-key>"成功响应
200
返回本页已上传 Markdown 文件及读取下一页所需的分页标记。
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
items | 是 | array<SourceResourceFile> | 当前分页中的记录。 |
nextCursor | 是 | string | null | 当前接口返回的分页标记。只能在接口和筛选条件不变时继续使用；被拒绝时请移除 cursor 并从第一页重新读取。 |
成功响应示例
json
{
"items": [
{
"sourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
"knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
"directoryId": "directory-11111111-1111-4111-8111-111111111111",
"name": "guide.md",
"relativePath": "handbook/guide.md",
"generatedPath": "pages/handbook/guide.md",
"contentType": "text/markdown; charset=utf-8",
"sizeBytes": 1024,
"resourceRevision": 1,
"contentRevision": 1,
"state": "available",
"workProgress": {
"required": 8,
"completed": 8,
"activeKinds": [],
"blockingKind": null,
"retryingKind": null
},
"failure": null,
"generatedOutputStatus": "current_available",
"actions": [
{
"kind": "open_generated_file",
"method": "GET",
"href": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md",
"scope": "source_file"
}
],
"links": {
"self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111",
"generatedContent": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fhandbook%2Fguide.md",
"search": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=guide.md"
},
"createdAt": "2026-06-17T00:00:00.000Z"
}
],
"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 | 当前接口所需的数据暂时不可用。 |