Register File

Prerequisites

You have an Alibaba Cloud Model Studio API key (see the API Key page in the console) and authentication configured. For details, see RAG API overview and Authentication. Data import endpoints use the same base URL and authentication as other RAG APIs, with the path prefix /api/v1/connector/dash/.

Endpoint

POST /api/v1/connector/dash/addFile Final step of file upload. After uploading the file content to OSS, call this endpoint to register the file in the data center. Full upload flow: 1) Call applyFileUploadLease to get a lease → 2) PUT the file to OSS using the returned URL → 3) Call this endpoint to register the file.

The category ID parameter is named category, not categoryId. This differs from listFile, addFilesFromAuthorizedOss, and other endpoints that use categoryId — don't confuse the two.

Request body

Field	Required	Type	Description
`leaseId`	Yes	string	Upload lease ID, the `fileUploadLeaseId` returned by the `applyFileUploadLease` endpoint.
`category`	Yes	string	Category ID (the field is named `category`, not `categoryId`). Returned by `listCategory`. Pass `default` to use the system default category; when categoryType is `SESSION_FILE`, pass `default`.
`categoryType`	No	string	Category type. Defaults to `UNSTRUCTURED`. `UNSTRUCTURED`: a category used to build Knowledge Bases. `SESSION_FILE`: files used for agent session interactions. When using `SESSION_FILE`, applyFileUploadLease must also receive `SESSION_FILE` as categoryType; such files are valid only for the current session and expire once it closes (at most 7 days). They cannot be stored long term.
`parser`	Yes	string	Parser type. `AUTO_SELECT` picks a parser automatically; `DOCMIND` intelligent document parsing; `DOCMIND_DIGITAL` digital document parsing; `DOCMIND_LLM_VERSION` LLM-based document parsing; `DASH_QWEN_VL_PARSER` Qwen VL parsing (requires parserConfig); `DOCMIND_LLM_VERSION_MEDIA` audio and video parsing. When categoryType is `UNSTRUCTURED`, files are parsed according to the category's data parsing settings; when it is `SESSION_FILE`, the system uses its default parsing method, which cannot be changed.
`tags`	No	array<string>	Tags associated with the file. Empty by default (no tags). Up to 100 tags; the total length of all tags must not exceed 700 characters; each tag is at most 32 characters.
`originalFileUrl`	No	string	Associates a URL with the file. When building a document-search Knowledge Base, the platform records this link and returns it with the file's recall results during agent conversations (via the `docUrl` field). The agent application must have the Knowledge Base enabled and answer-source display turned on, otherwise this parameter has no effect.
`parserConfig`	No	object	Parser configuration. Required only when parser is `DASH_QWEN_VL_PARSER`; not needed for other parsers. Sub-fields: `modelName` (string, visual parsing model; enum `qwen3-vl-plus`), `modelPrompt` (string, parsing prompt, 1 to 1500 characters).

Request example

curl -X POST "$BASE_URL/api/v1/connector/dash/addFile" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leaseId": "lease_abc123",
    "category": "cate_abc123",
    "categoryType": "UNSTRUCTURED",
    "parser": "AUTO_SELECT",
    "tags": ["产品", "指南"]
  }'

BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com ({workspace_id} is the Workspace ID), and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API key.

Response example

Returns 200 on success.

{
  "code": "Success",
  "status_code": 200,
  "data": {
    "fileId": "file_abc123"
  },
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response fields

Field	Type	Description
`code`	string	Response code. `Success` on success.
`message`	string	Error or informational message; an empty string on success.
`requestId`	string	Unique request identifier. Include this ID when reporting an issue.
`data`	object	Registration result. Sub-fields: `fileId` (string, ID of the registered file), `parser` (string, parser actually used), `status` (string, file registration status; `SUCCESS` on success).
`status`	integer	Business status code. `200` on success, `400` for failures such as invalid parameters. Note that the HTTP status code remains 200 even on failure, so rely on this field and `code` to determine the result.

Error codes

HTTP status code	Error code `code`	Description
400	`InvalidParameter`	Invalid request parameters. Example `message`: `Required parameter missing or invalid.`
401	`InvalidApiKey`	Authentication failed; the API key is invalid or missing. Example `message`: `Invalid API-key provided.`

On business failures the HTTP status code remains 200. Check status and code in the response body to determine the result.

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes

Prerequisites

Endpoint

Request body

Request example

Response example

Response fields

Error codes