Create knowledge base

Create knowledge base metadata that agents can reference. This interface does not perform file parsing, indexing, or retrieval; these operations are handled by other resource operations or tool interfaces.

POST 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.

catalog_asset_refs[].uri cannot contain credentials or sensitive query parameters; catalog_asset_refs[].config and metadata cannot contain keys or provider run or session references. The workspace and current user in the path are determined by the server and do not need to be passed in the request body.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/knowledge-bases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "<CATALOG_ID>",
        "role": "source"
      }
    ],
    "visibility": "workspace",
    "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.

Request body

Parameters	Type	Is it required	Description
name	string	Yes	Knowledge base name, length cannot exceed 128.
id	string	No	Knowledge base ID. Generated by the server if not provided.
description	string	No	Knowledge base description, length cannot exceed 4096.
status	string	No	Status: draft, active, disabled, or archived; if not provided, draft.
source_type	string	No	Source type: manual, catalog_resource, file_collection, external_drive, or connector_export; if not provided, manual.
catalog_asset_refs	object[]	No	The associated Catalog asset. Each element must provide type and at least id or uri.
default_retrieval_profile_ref	string	No	Default to retrieve configuration reference.
tags	string[]	No	Label.
owner_user_id	string	No	Resource owner ID. If not provided, the current user ID is used.
visibility	string	No	Visible range: private or workspace; if not provided, private.
index_status	string	No	Index status: empty, indexing, ready, or failed; if not provided, empty.
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	String key-value label.
annotations	object	No	String key-value comment.
metadata	object	No	Extended metadata. May not contain keys, provider running information, or session references.

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

Successful response

Returns 201 on success. data is the newly created knowledge base metadata; successful creation does not mean that the content has been parsed or indexed.

{
  "code": 0,
  "data": {
    "id": "kb_01",
    "workspace_id": "ws_01",
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "cat_01",
        "role": "source"
      }
    ],
    "tags": ["产品", "文档"],
    "owner_user_id": "user_01",
    "visibility": "workspace",
    "index_status": "ready",
    "version": 1,
    "created_by": "user_01",
    "updated_by": "user_01",
    "created_at": "2026-08-18T01:00:00Z",
    "updated_at": "2026-08-18T01: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	Knowledge base name and description; description is not returned when no description is set.
data.description	string	Knowledge base name and description; description is not returned when no description is set.
data.status	string	Knowledge base status.
data.source_type	string	Knowledge base source type.
data.catalog_asset_refs	object[]	The associated Catalog asset; not returned if not set. Each item can contain type, id, uri, version, role, and config.
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.
data.index_status	string	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	Resource version, created as 1.
data.labels	object	String key-value label and comment; not returned if not set.
data.annotations	object	String key-value label and comment; not returned if not set.
data.metadata	object	Extended 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 name, status, source type, 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.
409	4（ALREADY_EXISTS）	The same knowledge base ID already exists in the current workspace.	Use a new ID, or query and update an existing knowledge base instead.
503	15（UNAVAILABLE）	The knowledge base service is temporarily unavailable.	Try again later.

Follow-up operations

Save data.id, and then call Query knowledge base details to confirm the metadata.

Last updated on Sep 3, 2026