Skip to main content
Events

发送 Session Event

向 Forward Session 写入支持的用户输入事件。

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

请求头

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

路径参数

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

请求体参数

参数类型是否必填说明
eventsarray是要追加的 Event 对象数组。
events[].typestring是输入 Event 类型。
events[].contentarray条件必填user.message 必填，必须为非空 content block 数组，仅支持 text、image 类型。
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.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": "Continue the analysis."
        }
      ]
    }
  ]
}'

示例响应

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 规则过滤。

错误

下表中的“-”表示响应不包含 error.code。
HTTPTypeCode触发条件
503api_errorsession_materialization_busy会话配置刷新冲突；响应包含 Retry-After: 1。
400invalid_request_errorinvalid_request_body请求体无法解析或结构不合法。
400invalid_request_errorinvalid_requestevents 为空、数量超限或缺少类型。
400invalid_request_errorinvalid_eventEvent 类型或字段不合法。
404not_found_errorsession_not_foundSession 不存在。
404not_found_error-运行时未找到 Session 或待处理的 Pending Action。
409conflict_erroridentity_disabledIdentity 已停用，不能发起新的执行。
409invalid_request_errorsession_archivedSession 已归档。
409invalid_request_error-当前 Session 正在处理 Turn，暂不能新建 Turn。
401authentication_error-未通过 Forward 身份验证。

备注

  • 收到 session_materialization_busy 时，按 Retry-After 退避重试，沿用原请求体和 Idempotency-Key（如有）；持续冲突时检查 Session 状态。
  • 允许写入的类型包括 user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result 和 user.define_outcome。
  • Identity 停用不会取消已接受的执行。停用期间，仅匹配真实待处理动作的工具确认或工具结果可继续提交，不能混入新的用户消息；重新启用后可在原 Session 中继续新一轮对话。详见停用 Identity。
  • 响应不会返回运行时原始 event JSON。

相关

列出 Session Events

订阅 Session Events