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.

HTTP
POST $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/local-files/upload

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the knowledge base list to obtain the target knowledge base ID.

Set the operation-specific values used in the request:

$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¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/local-files/upload" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./product-guide.pdf"

Parameter reference

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.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "file_id": "file_01"
  }
}

Field reference

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¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "file is required",
  "data": null
}

Field reference

Common HTTP errors¶

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.

Last updated on Sep 15, 2026