Skip to main content

Upload file

Upload an Agent API source file through multipart/form-data and obtain a file_id.

Endpoint

POST /agents/file Uploads a source file to the current workspace with multipart/form-data. A successful call returns 200 and file metadata. Uploading and writing to an environment are separate steps; after obtaining the file_id, write the file to an environment.

Request body

file binary file (required)File part in the form; the filename comes from the form and mime_type is detected by the serviceNo purpose field is required. The service saves the file with the Agent API origin. Upload size is limited by the gateway and content inspection.

Request example

curl -sS -X POST "$BASE_URL/agents/file" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -F "file=@input.txt;type=text/plain"

Response fields

id stringSource file IDtype stringResource type, fixed as filefilename stringFile namemime_type stringMIME type detected by the servicesize_bytes integerFile size in bytesdownloadable booleanPlatform metadata flag; not a substitute for the inspection check used when writing to an environmentstatus stringFile status: checking, available, rejected, type_rejected, and so oncreated_at stringCreation time, RFC3339 timestamprequest_id stringIdentifier of this upload requestA successful upload does not mean the file passed inspection or can be written to an environment immediately. Writing can fail or wait while the file is being inspected or after inspection fails.

Response example

{
  "id": "file_xxx",
  "type": "file",
  "filename": "input.txt",
  "mime_type": "text/plain",
  "size_bytes": 18,
  "downloadable": false,
  "status": "checking",
  "created_at": "2026-11-06T00:00:00Z",
  "request_id": "req_xxx"
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_error, param=fileSelect a non-empty file and retry
413invalid_request_error / invalid_request_error, param=fileReduce the file size and retry
—Can return No such File or a batch purpose limitUse /agents/file to upload source files
A gateway rejection can use a different status and structure. Keep the HTTP status, x-request-id, and file metadata for troubleshooting.