跳转到主要内容
POST /api/v1/forward/sessions/{session_id}/events 向 Session 追加输入事件。调用方不能伪造 agent 事件或 session 状态事件。

​
请求头

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

​
路径参数

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

​
请求体参数

参数类型是否必填说明
eventsarray是要追加的 Event 对象数组。
events[].typestring是输入 Event 类型。
events[].contentarray条件必填user.message 和 system.message 必填，必须为非空 content block 数组。
events[].file_attachmentsarray否user.message 的文件附件元数据。
events[].tool_use_idstring条件必填user.tool_confirmation 和 user.tool_result 必填。
events[].custom_tool_use_idstring条件必填user.custom_tool_result 必填。
events[].resultstring条件必填user.tool_confirmation 必填，取值 allow 或 deny。
events[].deny_messagestring否拒绝原因，仅 result=deny 时使用。
events[].descriptionstring条件必填user.define_outcome 必填。
events[].rubricobject条件必填user.define_outcome 必填。
events[].reasonstring否user.interrupt 的中断原因。
events[].is_errorboolean否工具结果事件的错误标记。

​
示例请求

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"
    }
  ]
}

​
响应字段

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

​
错误

HTTPTypeCode触发条件
400invalid_request_errorinvalid_eventEvent 类型或字段不合法。
404not_found_errorsession_not_foundSession 不存在。
409conflict_errorsession_archivedSession 已归档。
409conflict_errorturn_already_running当前 Turn 状态不允许新建 Turn。
404not_found_errorpending_action_not_found工具确认或结果找不到对应 Pending Action。
409conflict_errorpending_action_already_resolvedPending Action 已处理。
401authentication_errorauthentication_requiredPAT 无效或已过期。

​
注意事项

  • 允许写入的类型包括 user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome 和 system.message。
  • system.message 每次请求最多一条，必须是最后一个事件。
  • 响应不会返回运行时原始 event JSON。

​
相关

列出 Session Events

订阅 Session Events