发送 Session Event

向 Forward Session 写入用户或系统输入事件。

POST /api/v1/forward/sessions/{session_id}/events

向 Session 追加输入事件。调用方不能伪造 agent 事件或 session 状态事件。

​

请求头

Header	是否必填	说明
Authorization	是	Bearer <PAT>
Content-Type	是	application/json
Idempotency-Key	否	有副作用请求可选的幂等键。

​

路径参数

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

​

请求体参数

参数	类型	是否必填	说明
events	array	是	要追加的 Event 对象数组。
events[].type	string	是	输入 Event 类型。
events[].content	array	条件必填	user.message 必填，必须为非空 content block 数组。
events[].file_attachments	array	否	user.message 的文件附件元数据。
events[].tool_use_id	string	条件必填	user.tool_confirmation 和 user.tool_result 必填。
events[].custom_tool_use_id	string	条件必填	user.custom_tool_result 必填。
events[].result	string	条件必填	user.tool_confirmation 必填，取值 allow 或 deny。
events[].deny_message	string	否	拒绝原因，仅 result=deny 时使用。
events[].description	string	条件必填	user.define_outcome 必填。
events[].rubric	object	条件必填	user.define_outcome 必填。
events[].reason	string	否	user.interrupt 的中断原因。
events[].is_error	boolean	否	工具结果事件的错误标记。

​

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "file_attachments": []
    }
  ]
}'

​

示例响应

HTTP 200 OK

{
  "data": [
    {
      "id": "evt_xxx",
      "type": "user.message",
      "session_id": "sess_xxx",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "processed_at": "2026-06-22T11:00:00Z"
    }
  ]
}

​

响应字段

字段	类型	说明
data	array	创建后的 Event 对象数组，已按 Forward 规则过滤。

​

错误

HTTP	Type	Code	触发条件
400	invalid_request_error	invalid_event	Event 类型或字段不合法。
404	not_found_error	session_not_found	Session 不存在。
409	conflict_error	session_archived	Session 已归档。
409	conflict_error	turn_already_running	当前 Turn 状态不允许新建 Turn。
404	not_found_error	pending_action_not_found	工具确认或结果找不到对应 Pending Action。
409	conflict_error	pending_action_already_resolved	Pending Action 已处理。
401	authentication_error	authentication_required	PAT 无效或已过期。

​

注意事项

• 允许写入的类型包括 user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result 和 user.define_outcome。
• system.message 是公共 Event 类型，但不开放为 Forward 客户端写入事件。
• 响应不会返回运行时原始 event JSON。

​

相关

列出 Session Events

订阅 Session Events