Update knowledge base

Update knowledge base metadata. Each successful update increments version by one; this interface does not perform file parsing or indexing.

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

Before you call

First Query the knowledge base details to confirm the current metadata and version. 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.

• $KNOWLEDGE_BASE_ID: ID of the knowledge base to be updated.

Request example

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/knowledge-bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档（已审核）",
    "status": "active",
    "index_status": "ready",
    "tags": ["产品", "文档", "已审核"]
  }'

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Current workspace ID, must be consistent with X-Workspace-ID.
knowledge_base_id	string	Yes	The ID of the knowledge base to update.

Request body

All fields are optional; only the fields provided in the request are updated.

Parameters	Type	Is it required	Description
name	string	No	New name, length cannot exceed 128.
description	string	No	New description, length cannot exceed 4096.
status	string	No	draft, active, disabled, or archived.
source_type	string	No	manual, catalog_resource, file_collection, external_drive, or connector_export.
catalog_asset_refs	object[]	No	Replace all associated assets. Each must provide type and at least id or uri.
default_retrieval_profile_ref	string	No	Default to retrieve configuration reference.
tags	string[]	No	Replace all tags.
owner_user_id	string	No	Update owner user ID.
visibility	string	No	private or workspace.
index_status	string	No	empty, indexing, ready, or failed.
last_indexed_at	string	No	The most recent index time, in RFC 3339 format.
last_index_error	string	No	Recent index error message, length cannot exceed 4096.
labels	object	No	Replace string key-value label.
annotations	object	No	Replace string key value annotation.
metadata	object	No	Replaces extended metadata; must not contain keys, provider runtime information, or session references.

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

Successful response

Returns 200 on success. data is the updated knowledge base metadata, and data.version is increased by 1 than before the update.

{
  "code": 0,
  "data": {
    "id": "kb_01",
    "workspace_id": "ws_01",
    "name": "产品文档（已审核）",
    "status": "active",
    "source_type": "catalog_resource",
    "visibility": "workspace",
    "index_status": "ready",
    "version": 2,
    "updated_by": "user_01",
    "updated_at": "2026-08-18T02:00:00Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Knowledge base ID.
data.workspace_id	string	ID of the workspace to which it belongs.
data.name	string	The updated name and description; will not be returned if the description is not set.
data.description	string	The updated name and description; will not be returned if the description is not set.
data.status	string	Updated status and source type.
data.source_type	string	Updated status and source type.
data.catalog_asset_refs	object[]	Associated assets; not returned if not set.
data.default_retrieval_profile_ref	string	Default retrieval configuration reference; does not return if not set.
data.tags	string[]	Label; does not return if not set.
data.owner_user_id	string	Owner user ID; not returned if not set.
data.visibility	string	Visible range and index status.
data.index_status	string	Visible range and index status.
data.last_indexed_at	string	Recent index time and error message; not returned if not set.
data.last_index_error	string	Recent index time and error message; not returned if not set.
data.version	integer	The updated resource version.
data.labels	object	Extended tags, comments, and metadata; not returned if not set.
data.annotations	object	Extended tags, comments, and metadata; not returned if not set.
data.metadata	object	Extended tags, comments, and metadata; not returned if not set.
data.created_by	string	Creator and last updater ID; not returned if not set.
data.updated_by	string	Creator and last updater ID; not returned if not set.
data.created_at	string	Creation and last update times, in RFC 3339 format.
data.updated_at	string	Creation and last update times, in RFC 3339 format.

[] 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）	The request body cannot be parsed, the field value or asset reference does not meet the requirements, or the metadata contains sensitive references that are not allowed.	Check request fields and asset references; do not pass in credentials or session information.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
404	3（NOT_FOUND）	The knowledge base does not exist in the current workspace.	Check out knowledge_base_id, or consult the knowledge base list first.
503	15（UNAVAILABLE）	The knowledge base service is temporarily unavailable.	Try again later.

Follow-up operations

Call Query knowledge base details to confirm the updated metadata and version.

Last updated on Sep 3, 2026