# Query the knowledge base list

Paginated list of knowledge bases (semantic models) that can be read by the current workspace. First find the knowledge base ID through this interface, and then query the details or add a data source.

```text
GET https://moi.matrixorigin.cn/newmoi/semantic-models
```

## Preparation before calling

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`: The workspace ID to be queried is passed through the `X-Workspace-ID` Header.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/semantic-models?page_size=20&search=product&tags=product" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Query parameters

The interface supports server-side paging; continue to use the `next_page_token` returned in the response, and do not infer the last page based on the number of entries on the current page.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page_size` | integer | No | The number of items in a single page, ranging from `1` to `100`; when not transmitted, it is `20`. |
| `page_token` | string | No | `next_page_token` from the previous page response. |
| `search` | string | No | Search criteria for name or description. |
| `tags` | string[] | No | Tag filter condition. Repeat passing in parameters, such as `tags=product&tags=support`. |

`[]` after a type means an array. For example, `string[]` is an array of strings.

## Successful response

Returns `200` on success. Get the knowledge base of the current page from `data.items`; when `data.next_page_token` is empty or not returned, it means there is no next page.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "id": 401,
        "name": "product_docs",
        "description": "产品文档",
        "tables": [],
        "files": [],
        "source_counts": {
          "files": 2,
          "tables": 1,
          "total": 3
        },
        "created_at": 1735632000,
        "updated_at": 1735718400
      }
    ],
    "total": 1,
    "next_page_token": ""
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.items` | object[] | The knowledge base of the current page. |
| `data.items[].id` | integer | Knowledge base ID, `model_id` that can be used as a subsequent interface. |
| `data.items[].name` | string | Knowledge base name. |
| `data.items[].description` | string | Knowledge base description; may be omitted if not set. |
| `data.items[].tables` | JSON | Compatible legacy table source definition. |
| `data.items[].files` | JSON | Compatible legacy file source definition; may be omitted if not set. |
| `data.items[].source_counts` | object | Number of sources for list or detail path supplements. |
| `data.items[].source_counts.files` | integer | Number of file sources. |
| `data.items[].source_counts.tables` | integer | Table source number. |
| `data.items[].source_counts.total` | integer | Total number of sources. |
| `data.items[].created_at` | integer | Creation time as a Unix timestamp. |
| `data.items[].updated_at` | integer | Update time as a Unix timestamp. |
| `data.total` | integer | The total number of matches that match the current filter criteria. |
| `data.next_page_token` | string | The token passed in unchanged when reading the next page. |

In field paths, `[]` means each item in an array. For example, `data.items[].id` is the `id` field of each item in `data.items`.

## Read next page

When `data.next_page_token` is non-empty, pass it into the next request as `page_token` until an empty token is returned.

## Error response

The same envelope is returned on request failure, where `data` is `null`.

```json
{
  "code": "ErrParamInvalid",
  "msg": "page_size is invalid",
  "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`
  - `page_size` is not an integer from `1` to `100`.
  - Correct the page size 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 read the knowledge base collection.
  - Check workspace and object authorization.
* - `500`
  - `ErrServer`
  - The service failed to complete the list query.
  - Keep the desensitized response information and try again.
```

## Follow-up operations

Use `data.items[].id` [Query knowledge base details](get-knowledge-base.md).