# Create knowledge base

Create knowledge base metadata that agents can reference. This interface does not perform file parsing, indexing, or retrieval; these operations are handled by other resource operations or tool interfaces.

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/knowledge-bases
```

## Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, passed through the `X-Workspace-ID` Header and also as `workspace_id` in the path.

`catalog_asset_refs[].uri` cannot contain credentials or sensitive query parameters; `catalog_asset_refs[].config` and `metadata` cannot contain keys or provider run or session references. The workspace and current user in the path are determined by the server and do not need to be passed in the request body.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/knowledge-bases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "<CATALOG_ID>",
        "role": "source"
      }
    ],
    "visibility": "workspace",
    "index_status": "ready",
    "tags": ["产品", "文档"]
  }'
```

## Path parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | Current workspace ID, must be consistent with `X-Workspace-ID`. |

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Knowledge base name, length cannot exceed 128. |
| `id` | string | No | Knowledge base ID. Generated by the server if not provided. |
| `description` | string | No | Knowledge base description, length cannot exceed 4096. |
| `status` | string | No | Status: `draft`, `active`, `disabled`, or `archived`; if not provided, `draft`. |
| `source_type` | string | No | Source type: `manual`, `catalog_resource`, `file_collection`, `external_drive`, or `connector_export`; if not provided, `manual`. |
| `catalog_asset_refs` | object[] | No | The associated Catalog asset. Each element must provide `type` and at least `id` or `uri`. |
| `default_retrieval_profile_ref` | string | No | Default to retrieve configuration reference. |
| `tags` | string[] | No | Label. |
| `owner_user_id` | string | No | Resource owner ID. If not provided, the current user ID is used. |
| `visibility` | string | No | Visible range: `private` or `workspace`; if not provided, `private`. |
| `index_status` | string | No | Index status: `empty`, `indexing`, `ready`, or `failed`; if not provided, `empty`. |
| `last_indexed_at` | string | No | The most recent index time, in RFC 3339 format. |
| `last_index_error` | string | No | Recent index error message, length cannot exceed 4096. |
| `labels` | object | No | String key-value label. |
| `annotations` | object | No | String key-value comment. |
| `metadata` | object | No | Extended metadata. May not contain keys, provider running information, or session references. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Successful response

Returns `201` on success. `data` is the newly created knowledge base metadata; successful creation does not mean that the content has been parsed or indexed.

```json
{
  "code": 0,
  "data": {
    "id": "kb_01",
    "workspace_id": "ws_01",
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "cat_01",
        "role": "source"
      }
    ],
    "tags": ["产品", "文档"],
    "owner_user_id": "user_01",
    "visibility": "workspace",
    "index_status": "ready",
    "version": 1,
    "created_by": "user_01",
    "updated_by": "user_01",
    "created_at": "2026-08-18T01:00:00Z",
    "updated_at": "2026-08-18T01:00:00Z"
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` on success. |
| `data.id` | string | Knowledge base ID. |
| `data.workspace_id` | string | ID of the workspace to which it belongs. |
| `data.name` | string | Knowledge base name and description; `description` is not returned when no description is set. |
| `data.description` | string | Knowledge base name and description; `description` is not returned when no description is set. |
| `data.status` | string | Knowledge base status. |
| `data.source_type` | string | Knowledge base source type. |
| `data.catalog_asset_refs` | object[] | The associated Catalog asset; not returned if not set. Each item can contain `type`, `id`, `uri`, `version`, `role`, and `config`. |
| `data.default_retrieval_profile_ref` | string | Default retrieval configuration reference; does not return if not set. |
| `data.tags` | string[] | Label; does not return if not set. |
| `data.owner_user_id` | string | Owner user ID; not returned if not set. |
| `data.visibility` | string | Visible range. |
| `data.index_status` | string | Index status. |
| `data.last_indexed_at` | string | Recent index time and error message; not returned if not set. |
| `data.last_index_error` | string | Recent index time and error message; not returned if not set. |
| `data.version` | integer | Resource version, created as `1`. |
| `data.labels` | object | String key-value label and comment; not returned if not set. |
| `data.annotations` | object | String key-value label and comment; not returned if not set. |
| `data.metadata` | object | Extended metadata; not returned if not set. |
| `data.created_by` | string | Creator and last updater ID; not returned if not set. |
| `data.updated_by` | string | Creator and last updater ID; not returned if not set. |
| `data.created_at` | string | Creation and last update times, in RFC 3339 format. |
| `data.updated_at` | string | Creation and last update times, in RFC 3339 format. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Error response

```json
{
  "code": 2,
  "message": "invalid knowledge base metadata"
}
```

### Common HTTP errors

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

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `2`（`INVALID_ARGUMENT`）
  - The request body cannot be parsed, the name, status, source type, or asset reference does not meet the requirements, or the metadata contains sensitive references that are not allowed.
  - Check request fields and asset references; do not pass in credentials or session information.
* - `401`
  - `6`（`UNAUTHENTICATED`）
  - Lack of valid identity credentials.
  - Check API Key.
* - `409`
  - `4`（`ALREADY_EXISTS`）
  - The same knowledge base ID already exists in the current workspace.
  - Use a new ID, or query and update an existing knowledge base instead.
* - `503`
  - `15`（`UNAVAILABLE`）
  - The knowledge base service is temporarily unavailable.
  - Try again later.
```

## Follow-up operations

Save `data.id`, and then call [Query knowledge base details](get-agent-knowledge-base.md) to confirm the metadata.