跳转到主要内容
POST /api/v1/cloud/sessions/{session_id}/events 向 Session 发送一个或多个可接受事件。user.message 会异步触发 Agent 执行，Agent 输出通过 list 或 stream 接口读取。

​
路径参数

参数类型说明
session_idstring以 sess_ 为前缀的 Session ID

​
请求头

请求头必填说明
Authorization是Bearer $QODER_PAT
Content-Type是application/json

​
请求体

字段类型必填说明
eventsarray是非空事件对象数组

​
支持的事件类型

类型必填字段说明
user.messagecontentcontent 必须是非空 content block 数组
user.interrupt无session_thread_id 可选
user.tool_confirmationtool_use_id, resultresult 为 allow 或 deny。deny_message 可选，且仅在 result = "deny" 时允许传入
user.tool_resulttool_use_id返回内置工具结果；content 和 is_error 可选
user.custom_tool_resultcustom_tool_use_id返回客户端自定义工具结果；content 和 is_error 可选
user.define_outcomedescription, rubricrubric 是对象，可取 {"type":"text","content":"..."} 或 {"type":"file","file_id":"file_..."}；不允许多余字段。max_iterations 可选，必须是 1–20 之间的整数。outcome_id（outc_ 前缀）由服务端生成，客户端不可传
system.messagecontentcontent 必须是非空文本 content block 数组。每次请求最多一个 system.message，且必须是 batch 的最后一个事件，紧跟在 user.message、user.tool_result 或 user.custom_tool_result 之后
user.message 和 system.message 不支持字符串形式的 content。

​
示例请求

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {"type": "text", "text": "Help me analyze the performance of this code."}
        ]
      }
    ]
  }'

​
示例响应

HTTP 200 OK 
{
  "data": [
    {
      "id": "evt_019e3bb2c153764da54e4d3acbef52b6",
      "type": "user.message",
      "content": [
        {"type": "text", "text": "Help me analyze the performance of this code."}
      ],
      "processed_at": "2026-05-18T15:27:11.187413896Z"
    }
  ]
}

​
人在环（Human-in-the-loop）响应

当事件流发出需要确认的 agent.tool_use 时，使用 user.tool_confirmation 响应： 
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "deny",
      "deny_message": "Do not delete files in this directory."
    }
  ]
}
当事件流发出 agent.custom_tool_use 时，由客户端执行该工具并使用 user.custom_tool_result 响应： 
{
  "events": [
    {
      "type": "user.custom_tool_result",
      "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
      "content": [{"type": "text", "text": "Order status: shipped"}]
    }
  ]
}

​
错误码

HTTP类型触发条件
400invalid_request_errorevents 为空、事件类型不支持、缺少必填字段、content block 非法或使用旧字段
401authentication_errorPAT 无效或过期
404not_found_errorSession 或 pending action 不存在
409invalid_request_errorSession 正在处理某个 turn，或其他 Session 状态冲突（注意：type 是 invalid_request_error，不是 conflict_error）

​
示例：400 content 非法

向 user.message 传入字符串而非 content block 数组： 
{
  "error": {
    "message": "Field 'content' must be a non-empty array of content blocks.",
    "type": "invalid_request_error"
  },
  "request_id": "2c9d3d8a-dd0f-4c27-b2ad-24c8719c97e1",
  "type": "error"
}

​
示例：404 Session 不存在

{
  "error": {
    "message": "Session 'sess_doesnotexist_xxxxxxxxxxxxxxxxxxxxxxxx' was not found.",
    "type": "not_found_error"
  },
  "request_id": "590c2a0c-1656-42d3-ba0c-32c755d22e77",
  "type": "error"
}

​
示例：409 Session 正在 running

在 Session 已经处于 running 状态时再发送 user.message： 
{
  "error": {
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion.",
    "type": "invalid_request_error"
  },
  "request_id": "ba018d2f-d6b0-4bbe-a53c-2241baca34fe",
  "type": "error"
}
完整错误信封格式参见 错误处理。

​
相关

Session 事件流

通过 SSE 实时获取 Agent 的思考、消息、工具调用与状态。