添加 Session 资源

POST /api/v1/forward/sessions/{session_id}/resources 向已创建 Session 的沙箱运行时环境追加挂载一个文件资源，适用于会话进行中需要临时上传文件的场景。文件必须先通过 Files API 上传；本接口只接受 type: "file"。

上传文件要求

用于本接口的文件建议在上传时明确指定 purpose=session_resource：

curl -X POST 'https://api.qoder.com.cn/api/v1/forward/files' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F 'file=@spec.md' \
  -F 'purpose=session_resource'

省略 purpose 时，Files API 默认按 user_upload 保存。该文件虽然可以添加到 Session，但不能通过 GET /api/v1/forward/files/{file_id}/content 下载，下载时会返回 403 permission_error。POST /api/v1/forward/sessions/{session_id}/resources 仅将已有文件挂载到 Session，不会将 user_upload 自动转换为 session_resource；如需后续下载，必须在上传文件时指定 purpose=session_resource。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`
Content-Type	是	`application/json`

路径参数

参数	类型	是否必填	说明
session_id	string	是	Session ID。

请求体参数

参数	类型	是否必填	说明
type	string	是	资源类型，必须为 `file`。
file_id	string	是	Files API 返回的 File ID，文件必须已上传完成。
mount_path	string	否	Agent 容器内挂载路径；省略时由 Forward 根据文件名生成，默认挂载到 `/data/workspace/<文件名>`。

示例请求

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/resources' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "file",
  "file_id": "file_019e6a18dc09abcd",
  "mount_path": "/data/workspace/spec.md"
}'

示例响应

HTTP 200 OK

{
  "id": "sesr_0e4323e8f47ba34853f5409e",
  "type": "file",
  "file_id": "file_019e6a18dc09abcd",
  "mount_path": "/data/workspace/spec.md",
  "created_at": "2026-06-23T05:53:19Z",
  "updated_at": "2026-06-23T05:53:38Z"
}

响应字段

字段	类型	说明
id	string	Session 资源 ID，以 `sesr_` 为前缀。
type	string	资源类型，固定为 `file`。
file_id	string	挂载的 File ID。
mount_path	string	文件在 Agent 容器内的实际挂载路径。
created_at	string	资源创建时间，RFC 3339。
updated_at	string	资源更新时间，RFC 3339。

通知 Agent 文件

挂载文件成功后，Agent 不会自动感知新文件。请通过发送 Session Events接口发送一条 user.message，并在消息中告知返回的文件路径：

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [{
    "type": "user.message",
    "content": [
      {"type": "text", "text": "帮我分析一下文件"},
      {"type": "text", "text": "文件路径：/data/workspace/spec.md"}
    ]
  }]
}'

消息中的路径请使用添加资源时返回的 mount_path。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_request_body`	请求体 JSON 不合法。
400	`invalid_request_error`	`invalid_resource`	`type` 不为 `file`、缺少 `file_id`，或字段包含控制字符。
404	`not_found_error`	`session_not_found`	Session 不存在。
404	`not_found_error`	`file_not_found`	File 不存在或已删除。
409	`conflict_error`	`session_archived`	Session 已归档。
409	`conflict_error`	`resource_conflict`	挂载路径与 Session 已挂载资源的路径冲突，或文件已挂载到当前 Session。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

文件必须先通过 Files API 上传成功；挂载成功后 Agent 即可在容器内读取该文件，但仍需发送 Event 通知 Agent 文件路径，参见通知 Agent 文件。
省略 mount_path 时，Forward 以 /data/workspace/<文件名> 生成默认挂载路径；多个同名文件请显式指定 mount_path 避免覆盖。
本接口只支持追加文件资源，其他资源类型不会被接受。
Session 已归档时不能追加资源；如需继续使用，请创建新的 Session。
添加成功的资源会返回在获取 Session 和列出 Sessions 接口响应的 resources 字段中；无资源时为空数组。

​上传文件要求

​请求头

​路径参数

​请求体参数

​示例请求

​示例响应

​响应字段

​通知 Agent 文件

​错误

​备注

​相关

创建 Session

上传文件