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

```text
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](upload-local-file.md). 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

```bash
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.

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](list-data-processing-jobs.md) to confirm that source processing is completed before using the knowledge base.