> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 发送 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` 和 `system.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 | 否    | 工具结果事件的错误标记。                                                 |

## 示例请求

```bash theme={null}
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**

```json theme={null}
{
  "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`。
* `system.message` 每次请求最多一条，必须是最后一个事件。
* 响应不会返回运行时原始 event JSON。

## 相关

<CardGroup cols={2}>
  <Card title="列出 Session Events" icon="list" href="/cloud-agents/api/forward/sessions/list-events" />

  <Card title="订阅 Session Events" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>