# Upload local files

Upload local files for use in creating or appending knowledge base sources. Successful upload only means that the file has been saved, but does not mean that the content is retrievable.

```text
POST https://moi.matrixorigin.cn/newmoi/semantic-models/{model_id}/local-files/upload
```

## Preparation before calling

First [query the knowledge base list](list-knowledge-bases.md) to obtain the target knowledge base ID. 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 `X-Workspace-ID` Header.
- `$MODEL_ID`: Target knowledge base ID.

The request type of this interface is `multipart/form-data`; the example uses `curl -F` to submit the file and do not add `Content-Type: application/json`.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models/$MODEL_ID/local-files/upload" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./product-guide.pdf"
```

## Path parameters

| Parameters | Type | Description |
| --- | --- | --- |
| `model_id` | integer | Target knowledge base ID. |

## Form fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | Yes | The local file to upload. |

## Successful response

Returns `200` on success. Save `data.file_id`, construct the value into the `local_file` source, and then call the add data source interface.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "file_id": "file_01"
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.file_id` | string | ID of the uploaded file; use this value when adding a local file source. |

## Error response

```json
{
  "code": "ErrParamInvalid",
  "msg": "file 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 multipart file named `file` is missing, or `model_id` is invalid.
  - Resubmit the file using `multipart/form-data` and check the path ID.
* - `401`
  - `ErrUnauthorized`
  - The API Key is invalid or has expired.
  - Check API Key.
* - `403`
  - `ErrForbidden`
  - The caller does not have permission to upload files to the knowledge base.
  - Check workspace and object authorization.
* - `404`
  - `ErrNotFound`
  - The knowledge base does not exist or is not visible to the current caller.
  - Relist the knowledge base and confirm the ID.
* - `500`
  - `ErrServer`
  - The service failed to store the file.
  - Keep the desensitized response information and try again.
```

## Follow-up operations

Use `data.file_id` [Add data source](add-data-sources.md).