上传文件

上传文本类文件，供 Session、工具或 Agent 输出使用。

POST /v1/files

上传一个文本类文件，并返回 File 对象。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>
Content-Type	是	multipart/form-data

​

请求体

字段	类型	必选	说明
file	file	是	文本类文件内容。支持类型见支持上传的文件类型
name	string	否	存储文件名。不传时使用上传文件名。服务端清理后长度必须为 1-255 byte，且不能是 . 或 ..
purpose	string	否	文件用途。默认 user_upload，见 File purpose
metadata	JSON string	否	作为表单字段传入的合法 JSON。原始长度最大 8 KB，省略时为 {}

​

示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "name=my-document.txt" \
  -F "purpose=user_upload" \
  -F 'metadata={"project":"demo"}'

​

示例响应

HTTP 201 Created

{
  "created_at": "2026-05-18T15:33:44Z",
  "file_id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "filename": "my-document.txt",
  "metadata": {
    "project": "demo"
  },
  "mime_type": "text/plain",
  "purpose": "user_upload",
  "size_bytes": 110,
  "status": "ready",
  "updated_at": "2026-05-18T15:33:45Z"
}

​

响应字段

字段	类型	说明
file_id	string	File ID，前缀为 file_
filename	string	存储后的文件名
size_bytes	integer	文件大小，单位 byte
mime_type	string	上传时提供或根据文件名检测出的 MIME type
purpose	string	文件用途，见 File purpose
status	string	文件状态，见 File status
metadata	JSON value	上传时传入的 metadata JSON
created_at	string	UTC 创建时间，RFC 3339 格式
updated_at	string	UTC 更新时间；与 created_at 不同时返回
session_id	string	文件关联 Session 时返回

​

注意事项

• multipart 请求体限制约为 5 MB 文件内容加上表单开销。
• 只接受文本类文件。二进制文档、图片、音视频和压缩包会被拒绝。
• 服务端会对 name 取基础文件名，并将路径分隔符或空字节替换为 _。

​

错误码

HTTP	type	触发条件
400	invalid_request_error	缺少 file、multipart 表单非法、文件类型不支持、purpose 非法、name 非法、metadata 非法或请求体过大
401	authentication_error	缺少或无效的认证令牌
500	api_error	文件存储后端不可用

完整错误信封说明详见 错误参考。

​

相关

附加与下载文件

上传文件为 Agent 提供上下文，并下载 Agent 产出的文件。