Register File

Final step of the upload flow — register an OSS-uploaded file with the data center.

POST

/api/v1/connector/dash/addFile

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/connector/dash/addFile" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leaseId": "lease_abc123",
    "category": "cate_abc123",
    "categoryType": "UNSTRUCTURED",
    "parser": "AUTO_SELECT",
    "tags": ["product", "guide"]
  }'

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

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.

Authorizations

string

header

required

DashScope API Key, obtained from the API Key page in the console.

Body

application/json

string

required

Upload lease ID. Returned by applyFileUploadLease.

string

required

Category ID (the field is named category, not categoryId). Returned by listCategory.

enum<string>

required

Parsing method.

Available options:AUTO_SELECT,DASHSCOPE_DOCMIND,DOCUMENT_PARSE_LLM

enum<string>

default"UNSTRUCTURED"

Category type.

Available options:UNSTRUCTURED,SESSION_FILE

string[]

File tags.

Required range:items: 1–100

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.

object

Parser configuration. Required only when parser is DASH_QWEN_VL_PARSER; not needed for other parsers.

Show child attributes

enum<string>

Visual parsing model.

Available options:qwen3-vl-plus

string

Parsing prompt, 1 to 1500 characters.

Required range:length: 1–1500

Response

200-application/json

string

Response code. Success on success.

string

Error or informational message; an empty string on success.

string

Unique request identifier. Include this ID when reporting an issue.

object

Show child attributes

string

ID of the registered file.

string

Parser actually used.

string

File registration status; SUCCESS on success.

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.