Create a knowledge base and add data sources

Create a knowledge base and submit the initial data source at the same time. A successful request only means that the source record and processing task have been created, but does not mean that the content is retrievable.

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

Preparation before calling

First confirm the source: Catalog tables, Catalog files and batch selection can only reference data already in the Catalog; local files first obtain the file ID through Upload local file. 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.

For direct sources, provide fields by source type:

Source type	Required fields
catalog_table	table_id
catalog_file	file_id, volume_id
local_file	The uploaded file_id and original file_name

source_selections can select only within a Catalog Database or Volume; do not pass data sources outside Catalog.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models/create-with-sources" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "$KNOWLEDGE_BASE_NAME",
    "sources": [
      {
        "source_type": "catalog_table",
        "table_id": $TABLE_ID
      }
    ]
  }'

Request body

In addition to the knowledge base name, submit a direct source or source selection.

Field	Type	Required	Description
name	string	Yes	The name of the knowledge base.
description	string	No	Knowledge base description.
image_index_enabled	boolean	No	Whether to enable image indexing at creation time.
files	object	No	File index extension configuration; the service will complete the fixed index settings required to create the knowledge base.
sources	object[]	No	Source added directly.
sources[].source_type	string	Conditionally required	Source type.
sources[].table_id	integer	Conditionally required	catalog_table The table ID of the source.
sources[].file_id	string	Conditionally required	The file ID of the file source.
sources[].file_name	string	Conditionally required	local_file The original file name of the source.
sources[].volume_id	integer	Conditionally required	catalog_file The volume ID of the source.
source_selections	object[]	No	Rules for selecting sources by database or volume.
source_selections[].kind	string	Conditionally required	database_tables or volume_files.
source_selections[].database_id	integer	Conditionally required	Catalog Database ID of database_tables.
source_selections[].volume_id	integer	Conditionally required	Catalog Volume ID of volume_files.
source_selections[].all_selected	boolean	Yes	true selects all objects in the current range; false must provide the corresponding explicit selection ID.
source_selections[].selected_table_ids	array	Conditionally required	Catalog table IDs explicitly selected when all_selected is false.
source_selections[].selected_file_ids	array	Conditionally required	Catalog file IDs explicitly selected when all_selected is false.
source_selections[].excluded_table_ids	array	No	Catalog table IDs to exclude when all_selected is true.
source_selections[].excluded_file_ids	array	No	Catalog file IDs to exclude when all_selected is true.

In field paths, [] means each item in an array. For example, sources[].source_type is the source_type field of each item in sources.

Successful response

On success, returns 201, which contains the new knowledge base, the created sources, and the processing of jobs. Save the origin’s row_id, which is used by subsequent origin, segmentation, and governance interfaces. The creation of jobs does not mean that source processing is complete.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "model": {
      "id": 401,
      "name": "product_docs",
      "source_counts": {
        "files": 0,
        "tables": 0,
        "total": 0
      },
      "created_at": 1735632000,
      "updated_at": 1735632000
    },
    "data_domain": {
      "model_id": 401,
      "catalog_id": 10,
      "database_id": 20,
      "raw_volume_id": 30,
      "processed_volume_id": 31,
      "ensure_status": "ready",
      "last_checked_at": 1735632000
    },
    "sources": [
      {
        "row_id": "src_01",
        "source_type": "table",
        "model_id": 401,
        "resource_id": "123",
        "ingest_status": "pending",
        "effective_enabled": true
      }
    ],
    "jobs": [
      {
        "job_id": "job_01",
        "source_id": "src_01",
        "model_id": 401,
        "job_type": "ingest",
        "job_status": "pending",
        "idempotency_key": "idem_01",
        "retry_count": 0
      }
    ]
  }
}

The response fields are as follows.

Field	Type	Description
code	string	OK on success.
msg	string	OK on success.
data.model	object	Snapshot of the new knowledge base.
data.model.id	integer	New knowledge base ID.
data.data_domain	object	The data field parsed for this knowledge base; contains the Catalog, database, and volume IDs, and the check status of the data field.
data.data_domain.ensure_status	string	The current guarantee status of the data field.
data.sources	object[]	Created source record.
data.sources[].row_id	string	Provenance record ID, this value is used by subsequent provenance, segmentation, and governance interfaces.
data.sources[].source_type	string	Source type: file or table.
data.sources[].ingest_status	string	Source processing status; pending does not mean that the content is retrievable.
data.sources[].effective_enabled	boolean	The current enabled status.
data.jobs	object[]	The processing task created for the source.
data.jobs[].job_id	string	Processing task ID.
data.jobs[].source_id	string	The associated source ID.
data.jobs[].job_type	string	Processing task type.
data.jobs[].job_status	string	The current status of the processing task.
data.jobs[].idempotency_key	string	The idempotent key for this processing task.
data.jobs[].retry_count	integer	The current number of recorded retries.

In field paths, [] means each item in an array. For example, data.sources[].row_id is the row_id field of each item in data.sources.

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 invalid, name is empty, the source type or source identifier is invalid, or the unsupported target_catalog_id is still passed in.	Correct the request body and try again.
401	ErrUnauthorized	The API Key is invalid or has expired.	Check API Key.
403	ErrForbidden	The caller does not have permission to create the knowledge base or read the selected source.	Check workspace and source object authorization.
409	ErrConflict	Repository or source status of service denial conflict.	Adjust requests after reading existing objects.
500	ErrServer	The service failed to create the knowledge base or submit source task.	Keep the desensitized response information and try again.

Follow-up operations

Use data.jobs[].job_id Query data processing tasks to confirm that source processing is completed before using the knowledge base.

Last updated on Sep 3, 2026