查询知识库列表

查询当前工作区的知识库元数据，并按状态、来源、可见范围、索引状态、所有者或关键词筛选。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/knowledge-bases

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求参数

请求示例

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/knowledge-bases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "status=active" \
  --data-urlencode "index_status=ready" \
  --data-urlencode "query=产品" \
  --data-urlencode "limit=20"

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	当前工作区 ID，必须与 X-Workspace-ID 一致。

查询参数

字段	类型	必填	说明
status	string	否	按知识库状态筛选。
source_type	string	否	按来源类型筛选。
visibility	string	否	按可见范围筛选。
index_status	string	否	按索引状态筛选。
owner_user_id	string	否	按所有者用户 ID 筛选。
query	string	否	按关键词筛选。
limit	integer	否	单次返回数量。未提供或小于等于 0 时为 50，最大为 200。
offset	integer	否	返回偏移量。未提供或小于 0 时为 0。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "kb_01",
        "workspace_id": "ws_01",
        "name": "产品文档",
        "status": "active",
        "source_type": "catalog_resource",
        "visibility": "workspace",
        "index_status": "ready",
        "version": 1,
        "created_at": "2026-08-18T01:00:00Z",
        "updated_at": "2026-08-18T01:00:00Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

字段说明

成功时返回 200。data.items 为本页知识库，data.total 为筛选结果总数。当前没有匹配项时，服务可能将 data.items 返回为 null；调用方应将其按空列表处理。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

通用字段

字段	类型	说明
code	integer	成功时为 0。

响应数据

字段	类型	说明
data.items	array或 null	本页知识库列表；没有匹配项时可能为 null。
data.total	integer	符合筛选条件的知识库总数。
data.limit	integer	本次实际采用的分页值。
data.offset	integer	本次实际采用的分页值。

items 数组元素

字段	类型	说明
data.items[].id	string	知识库 ID。
data.items[].workspace_id	string	所属工作区 ID。
data.items[].name	string	名称和说明；未设置说明时不返回。
data.items[].description	string	名称和说明；未设置说明时不返回。
data.items[].status	string	知识库状态和来源类型。
data.items[].source_type	string	知识库状态和来源类型。
data.items[].catalog_asset_refs	array	关联资产；未设置时不返回。成员说明见创建知识库中的关联资产字段。
data.items[].default_retrieval_profile_ref	string	默认检索配置引用；未设置时不返回。
data.items[].tags	array of string	标签；未设置时不返回。
data.items[].owner_user_id	string	所有者用户 ID；未设置时不返回。
data.items[].visibility	string	可见范围和索引状态。
data.items[].index_status	string	可见范围和索引状态。
data.items[].last_indexed_at	string	最近索引时间和错误信息；未设置时不返回。
data.items[].last_index_error	string	最近索引时间和错误信息；未设置时不返回。
data.items[].version	integer	资源版本。
data.items[].labels	object	扩展标签、注释和元数据；未设置时不返回。
data.items[].annotations	object	扩展标签、注释和元数据；未设置时不返回。
data.items[].metadata	object	扩展标签、注释和元数据；未设置时不返回。
data.items[].created_by	string	创建者和最近更新者 ID；未设置时不返回。
data.items[].updated_by	string	创建者和最近更新者 ID；未设置时不返回。
data.items[].created_at	string	创建和最近更新时间，采用 RFC 3339 格式。
data.items[].updated_at	string	创建和最近更新时间，采用 RFC 3339 格式。

错误响应

响应示例

{
  "code": 2,
  "message": "invalid knowledge base metadata"
}

字段说明

常见 HTTP 错误

字段	类型	说明
400	2（INVALID_ARGUMENT）	owner_user_id 或工作区参数无效。建议：检查筛选参数，不要在 ID 中使用路径分隔符。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。建议：检查 API Key。
503	15（UNAVAILABLE）	知识库服务暂不可用。建议：稍后重试。

后续操作

使用 data.items[].id 调用查询知识库详情。

最后更新于 2026 年 9 月 11 日