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://api.moi.matrixorigin.cn/v5/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://api.moi.matrixorigin.cn/v5/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": 123
      }
    ]
  }'

Request body

The example uses a fictitious table ID, 123. Replace it with the actual Catalog table ID, and replace <KNOWLEDGE_BASE_NAME>.

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

Field	Type	Required	Description
name	string	Yes	Nonempty knowledge base name, up to 255 Unicode characters, with no leading or trailing whitespace. Character rules are listed below.
description	string	No	Knowledge base description.
target_catalog_id	integer	No	Positive target Catalog ID; defaults to the workspace default Catalog.
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	array of 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[].upload_kind	string	No	Local file processing: unstructured or structured; omitted values use unstructured processing.
sources[].table_config	string	Conditionally required	JSON-serialized table import configuration required for structured uploads. Do not provide it for unstructured files.
source_selections	array of 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.

Names follow Catalog naming rules: start with a lowercase letter, digit, underscore, or Han character; subsequent characters may also contain hyphens (-) and periods (.). Examples include product_docs and 产品资料. Uppercase letters, spaces, and slashes (/) are not allowed. The name cannot be changed after creation.

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.

The example below is a response excerpt.

{
  "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.

Source records contain source, governance, and processing status fields. Before writing segments, query document details to obtain the current snapshot’s data.etag. See its source fields for the complete source schema.

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	array of 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 or null	Source processing status; pending does not mean that the content is retrievable.
data.sources[].effective_enabled	boolean	The current enabled status.
data.jobs	array of 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": "Bad Request"
}

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 Oct 19, 2026