Query the knowledge base list

Query the knowledge base metadata for the current workspace and filter by status, source, visible scope, index status, owner, or keywords.

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

Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID Header and also as workspace_id in the path.

Request example

curl --get "https://moi.matrixorigin.cn/newmoi/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"

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Current workspace ID, must be consistent with X-Workspace-ID.

Query parameters

Parameters	Type	Is it required	Description
status	string	No	Filter by knowledge base status.
source_type	string	No	Filter by source type.
visibility	string	No	Filter by visible range.
index_status	string	No	Filter by index status.
owner_user_id	string	No	Filter by owner user ID.
query	string	No	Filter by keyword.
limit	integer	No	Single return quantity. 50 when not provided or less than or equal to 0, up to 200.
offset	integer	No	Returns the offset. 0 when not provided or less than 0.

Successful response

Returns 200 on success. data.items is the knowledge base of this page, and data.total is the total number of filtered results.

{
  "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
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	object[]	Knowledge base list on this page.
data.items[].id	string	Knowledge base ID.
data.items[].workspace_id	string	ID of the workspace to which it belongs.
data.items[].name	string	Name and description; will not be returned if no description is set.
data.items[].description	string	Name and description; will not be returned if no description is set.
data.items[].status	string	Knowledge base status and source type.
data.items[].source_type	string	Knowledge base status and source type.
data.items[].catalog_asset_refs	object[]	Associated assets; not returned if not set. Each item can contain type, id, uri, version, role, and config.
data.items[].default_retrieval_profile_ref	string	Default retrieval configuration reference; does not return if not set.
data.items[].tags	string[]	Label; does not return if not set.
data.items[].owner_user_id	string	Owner user ID; not returned if not set.
data.items[].visibility	string	Visible range and index status.
data.items[].index_status	string	Visible range and index status.
data.items[].last_indexed_at	string	Recent index time and error message; not returned if not set.
data.items[].last_index_error	string	Recent index time and error message; not returned if not set.
data.items[].version	integer	Resource version.
data.items[].labels	object	Extended tags, comments, and metadata; not returned if not set.
data.items[].annotations	object	Extended tags, comments, and metadata; not returned if not set.
data.items[].metadata	object	Extended tags, comments, and metadata; not returned if not set.
data.items[].created_by	string	Creator and last updater ID; not returned if not set.
data.items[].updated_by	string	Creator and last updater ID; not returned if not set.
data.items[].created_at	string	Creation and last update times, in RFC 3339 format.
data.items[].updated_at	string	Creation and last update times, in RFC 3339 format.
data.total	integer	The total number of knowledge bases that meet the filter conditions.
data.limit	integer	The paging value actually used this time.
data.offset	integer	The paging value actually used this time.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response

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

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	owner_user_id or invalid workspace parameter.	Check filter parameters and do not use path separators in IDs.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
503	15（UNAVAILABLE）	The knowledge base service is temporarily unavailable.	Try again later.

Follow-up operations

Use data.items[].id to call Query knowledge base details.

Last updated on Sep 3, 2026