Import knowledge base definitions and semantic entries

Create knowledge bases from definitions and write their semantic entries in the same batch.

POST https://api.moi.matrixorigin.cn/v5/semantic-models/import

Before you call this API

Prepare current Workspace credentials and resource privileges. See Shared information for variables, import files, and operation boundaries.

Request body

curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/import" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @"$MODELS_IMPORT_JSON"

The example reads one FAQ definition from a JSON array file. After prevalidating items and dependencies, the service creates models and entries in one tenant transaction. It does not update by ID or synchronously complete upload, parsing, or index rebuilding. The request describes supported definition fields only, not complete backup/recovery of drawing configuration, vector indexes, chunk history, or all knowledge base states. Query first for unknown outcomes or errors; do not assume every error means nothing was created.

Field

Type

Required

Description

请求根

object or object[]

Yes

One object imports one definition; a nonempty array imports multiple. Response shape follows the root type.

name

string

Required for each item

Knowledge base name; must be nonempty after trimming during import.

description

string

No

Description; trimmed before saving.

tables

object[]

No

Source table declarations. Each contains db_name and a nonempty table_names string array.

files

object

No

Source file declaration containing a file_ids string array, not uploaded file contents.

entries

object[]

No

Semantic entries for this knowledge base; an empty list means none.

entries[].domain

string

No

Choose nl2sql or rag by entry kind. See shared information for defaults and rules.

entries[].kind

string

Required when entries exist

Entry kind allowed by this domain, such as standard_qa in the example.

entries[].key

string

Required when entries exist

Entry identifier within the same domain and kind.

entries[].tables

string[]

No

Source tables referenced by the entry; must match the model’s table set.

entries[].spec

JSON

Required when entries exist

Entry definition matching domain/kind.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "id": 101,
        "name": "Operations FAQ",
        "tables": [],
        "created_at": 1794408000,
        "updated_at": 1794408000,
        "source_counts": {
          "files": 0,
          "tables": 0,
          "total": 0
        },
        "semantic_model_kind": "standard",
        "drawing_number_policy": "overwrite_current"
      }
    ],
    "total": 1
  }
}

Field

Type

Description

code

string

OK on success.

msg

string

Response information.

data

object

Current operation result. Single-object imports return a knowledge base object directly.

data.items

object[]

Creation results for array requests. For a single-object request, data directly contains one knowledge base object.

data.total

integer

Number of created objects returned for this array request, not the Workspace total.

data.items[].id

integer

New knowledge base ID for subsequent details and source operations.

data.items[].name

string

Saved name.

data.items[].description

string

Description when present.

data.items[].tables

JSON

Source table declarations.

data.items[].files

JSON

Source file declarations when present.

data.items[].created_at

integer

Unix timestamp in seconds.

data.items[].updated_at

integer

Unix timestamp in seconds.

data.items[].source_counts

object

Count projection in the current creation response; does not establish completed parsing/indexing.

data.items[].semantic_model_kind

string

Knowledge base type; current imported definitions use standard model configuration.

data.items[].drawing_number_policy

string

Current model metadata. This request provides no drawing-specific configuration fields.

Error responses

Success returns HTTP 201. Validation, dependency, or permission errors do not mean successful import. Retain request information and read back as described in Errors and environments.

Last updated on