获取文件元数据

根据文件 ID 获取单个文件的元数据。

GET /v1/files/{file_id}

获取单个 File 对象。deleted 状态的文件不会通过该接口返回。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>

​

路径参数

参数	类型	必选	说明
file_id	string	是	File ID，前缀为 file_

​

示例请求

curl -X GET "https://api.qoder.com/api/v1/cloud/files/file_019e3bb8c1387743bf4ef115aae5acb1" \
  -H "Authorization: Bearer $QODER_PAT"

​

示例响应

HTTP 200 OK

{
  "created_at": "2026-05-18T15:33:44Z",
  "file_id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "filename": "qoder-test-upload.txt",
  "metadata": {},
  "mime_type": "text/plain",
  "purpose": "session_resource",
  "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	文件状态。获取单个文件时不会返回 deleted 状态的文件
metadata	JSON value	上传时传入的 metadata JSON
created_at	string	UTC 创建时间，RFC 3339 格式
updated_at	string	UTC 更新时间；与 created_at 不同时返回
session_id	string	文件关联 Session 时返回

​

错误码

HTTP	type	触发条件
401	authentication_error	缺少或无效的认证令牌
404	not_found_error	指定 ID 的文件不存在，或文件处于 deleted 状态

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

​

相关

附加与下载文件

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