Update knowledge base¶

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

HTTP
PATCH $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/knowledge-bases/{knowledge_base_id}

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First Query the knowledge base details to confirm the current metadata and version.

Set the operation-specific values used in the request:

$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¶

Input examples

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

Parameter reference

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.

Response example

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

Field reference

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¶

Response example

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

Field reference

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 15, 2026