Create knowledge base¶

Create an empty knowledge base. Data sources and semantic entries can be added individually after creation.

POST https://moi.matrixorigin.cn/newmoi/semantic-models

Preparation before calling¶

Prepare a personal access token and target workspace ID that has access to the target workspace and permission to create a knowledge base.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: The ID of the workspace to create the knowledge base, passed through the X-Workspace-ID Header.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<KNOWLEDGE_BASE_NAME>",
    "description": "<DESCRIPTION>",
    "tables": []
  }'

Request body¶

Field	Type	Required	Description
`name`	string	Yes	The name of the knowledge base.
`description`	string	No	Coverage and usage instructions.
`tables`	JSON	No	Compatible legacy table source definition. For new access sources, please use the add data source interface.
`files`	JSON	No	Compatible legacy file source definition. For new access sources, please use the add data source interface.

Successful response¶

Returns 201 on success. Save data.id and use it as model_id in subsequent interfaces.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 401,
    "name": "product_docs",
    "description": "产品文档",
    "tables": [],
    "source_counts": {
      "files": 0,
      "tables": 0,
      "total": 0
    },
    "created_at": 1735632000,
    "updated_at": 1735632000
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	integer	New knowledge base ID.
`data.name`	string	Name of the created knowledge base.
`data.description`	string	The saved description; may be omitted if not set.
`data.tables`	JSON	Compatible legacy table source definition.
`data.files`	JSON	Compatible legacy file source definition.
`data.source_counts`	object	Source count in creation snapshot; empty knowledge base entry is `0`.
`data.created_at`	integer	Unix timestamp.
`data.updated_at`	integer	Unix timestamp.

Error response¶

{
  "code": "ErrParamInvalid",
  "msg": "name is required",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The request body is not valid JSON, or `name` is missing.	Provide non-empty name and check JSON.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have permission to create a knowledge base.	Check workspace authorization.
`409`	`ErrConflict`	The service rejects duplicate or conflicting knowledge base definitions.	Modify the conflicting object or use an existing knowledge base.
`500`	`ErrServer`	The service failed to create the knowledge base.	Keep the desensitized response information and try again.

Follow-up operations¶

Use data.id Add data source or Upload local files.

Last updated on Sep 3, 2026