Request Upload Lease

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/applyFileUploadLease First step of uploading a file to the data center. Returns an OSS pre-signed URL and a lease ID for uploading the file content. Full upload flow: 1) Call this endpoint to get a lease → 2) PUT the file to OSS using the returned URL → 3) Call addFile to register the file.

File upload is a three-step flow:

Request a lease (this endpoint) — get the OSS pre-signed URL and leaseId.
PUT to OSS — upload the file binary via HTTP PUT using the returned param.url and param.headers.
Register the file (addFile) — register the uploaded file with the data center using leaseId.

sizeBytes must be passed as a string (for example "1048576"), not a number.

Request body

Field	Required	Type	Description
`category`	Yes	string	Category ID (the field is named `category`, not `categoryId`). Returned by `listCategory`.
`fileName`	Yes	string	File name, including the extension.
`sizeBytes`	Yes	string	File size in bytes, passed as a string.
`contentMd5`	Yes	string	MD5 of the file content (Base64-encoded), 1 to 64 characters.
`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`, addFile 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.
`useInternalEndpoint`	No	boolean	Whether to upload through the internal endpoint of the secure storage space. Defaults to false.

Request example

curl -X POST "$BASE_URL/api/v1/connector/dash/applyFileUploadLease" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "cate_abc123",
    "fileName": "product-guide.pdf",
    "sizeBytes": "1048576",
    "contentMd5": "d41d8cd98f00b204e9800998ecf8427e"
  }'

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",
  "message": "",
  "messageUnmodified": false,
  "requestId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "type": "OSS.PreSignedUrl",
    "param": {
      "url": "https://oss-example.aliyuncs.com/...",
      "method": "PUT",
      "headers": {
        "x-bailian-extra": "MTkxMDA3MzE0NjA0NDgzNA==",
        "Content-Type": "text/plain"
      }
    },
    "leaseId": "82845f78ab0343ada293c9595ed93dbf.1782191906659"
  },
  "status": 200
}

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	Lease result. Sub-fields: `type` (string, upload type. Always `OSS.PreSignedUrl`), `leaseId` (string, upload lease ID. Use it when registering the file), `param` (object, OSS upload parameters. Sub-fields: `url` (string, OSS pre-signed upload URL), `method` (string, HTTP method. Always `PUT`), `headers` (object, request headers required for the upload. Sub-fields: `x-bailian-extra` (string, Model Studio additional information), `Content-Type` (string, content type))).
`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