メインコンテンツへスキップ
POST /v1/sessions/{session_id}/events Session にイベント（通常はユーザーメッセージ）を送信し、Agent の処理をトリガーします。これは非同期操作です。メッセージが受け付けられた後、Agent はバックグラウンドで応答を生成し、SSE ストリームまたはイベント一覧 API で結果を取得できます。

​
パスパラメータ

パラメータ型説明
session_idstringSession ID（sess_ プレフィックス）

​
ヘッダー

名称必須値
AuthorizationはいBearer $QODER_PAT
Content-Typeはいapplication/json

​
リクエストボディ

フィールド型必須説明
eventsarrayはいイベントオブジェクトの配列
events[].typestringはいイベントタイプ
events[].contentstring | array条件付きメッセージ内容（user.message タイプ時は必須）
events[].content[].typestringはいコンテンツブロックタイプ（例: text）
events[].content[].textstringはいテキスト内容
events[].file_attachmentsarrayいいえuser.message の任意のファイル添付メタデータ。サーバーはイベントに保存し、ターン入力に転送します。
content は 2 つの形式をサポートします：
  • 簡略形式：文字列 "content": "テキスト内容"
  • 完全形式：コンテンツブロック配列 "content": [{"type": "text", "text": "テキスト内容"}]
プレーンテキストメッセージには簡略形式を推奨します。マルチメディアコンテンツ（画像など）を送信する場合は完全形式を使用してください。

​
サポートされるイベントタイプ

type説明必須フィールド
user.messageユーザーがメッセージを送信content
user.interruptユーザーが Agent の実行を中断-
user.tool_confirmation確認が必要な Agent ツール呼び出しを承認または拒否tool_use_id、result（allow または deny）
user.custom_tool_resultクライアント側カスタムツールの結果を返すcustom_tool_use_id。content は任意で、デフォルトは空のテキストブロック
user.define_outcomeユーザーが期待結果を定義サーバーが強制する追加フィールドなし
session.status_idleワーカー/Session 状態イベントサーバーが強制する追加フィールドなし
turn_completedワーカー終了イベントサーバーが強制する追加フィールドなし

​
Human-in-the-loop レスポンスイベント

ターンが人間の入力待ちで一時停止すると、ストリームは session.status_idle を stop_reason.type: "requires_action" と event_ids 配列付きで送信します。各 ID はレスポンスが必要なイベントを指します：
  • agent.tool_use の場合、user.tool_confirmation を送信し、tool_use_id に agent.tool_use イベントの id を設定します。
  • agent.custom_tool_use の場合、クライアントでカスタムツールを実行し、user.custom_tool_result を送信し、custom_tool_use_id に agent.custom_tool_use イベントの id を設定します。
ツール呼び出しの承認: 
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "allow"
    }
  ]
}
ツール呼び出しの拒否: 
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "deny",
      "deny_message": "このディレクトリのファイルを削除しないでください。"
    }
  ]
}
カスタムツール結果の返却: 
{
  "events": [
    {
      "type": "user.custom_tool_result",
      "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
      "content": [{"type": "text", "text": "Order status: shipped"}]
    }
  ]
}
user.custom_tool_result の content は文字列、テキストコンテンツブロック、またはテキストコンテンツブロックの配列を指定できます。返されるイベントではコンテンツブロックとして格納されます。 user.tool_confirmation の最新フィールドは result で、値は "allow" または "deny" です。サーバーはレガシーの decision（"approve" または "deny"）も result が存在しない場合のみ受け付け、返されるイベントには result として格納します。

​
リクエスト例

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": "このコードのパフォーマンス問題を分析してください"}
        ]
      }
    ]
  }'

​
レスポンス例

HTTP 202 Accepted 作成されたイベント一覧を返します。HTTP 202 はメッセージが受け付けられ、処理キューに入ったことを示します。 
{
  "data": [
    {
      "id": "evt_019e3bb2c153764da54e4d3acbef52b6",
      "type": "user.message",
      "content": [
        {"type": "text", "text": "このコードのパフォーマンス問題を分析してください"}
      ],
      "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
      "turn_id": "turn_019e3bb2c15376429b88e1f7976c1907",
      "schema_version": "1.0",
      "created_at": "2026-05-18T15:27:11.187413896Z",
      "processed_at": "2026-05-18T15:27:11.187413896Z"
    }
  ]
}

​
レスポンスフィールド

トップレベルレスポンス:
フィールド型説明
dataarray作成されたイベントオブジェクトの配列（リクエストと同じ順序）
イベントごとの共通フィールド:
フィールド型説明
idstringイベントの一意識別子（evt_ プレフィックス）
typestringイベントタイプ
contentstring or arrayイベント固有のコンテンツ。user.message はリクエスト形式を保持し、user.custom_tool_result はテキストブロックの配列として格納されます。
session_idstring所属する Session ID
turn_idstringイベントがターンに属する場合の Turn ID（turn_ プレフィックス）。user.message は新しい turn_id を作成します。
schema_versionstringSchema バージョン
created_atstring作成時刻（ISO 8601）
processed_atstring処理時刻（ISO 8601）
tool_use_idstringuser.tool_confirmation に存在
custom_tool_use_idstringuser.custom_tool_result に存在
resultstringuser.tool_confirmation に存在。"allow" または "deny"
deny_messagestringuser.tool_confirmation で result が "deny" の場合の任意の拒否理由
メッセージ送信後、Agent は非同期で処理を開始します。GET /v1/sessions/{session_id}/events/stream で Agent の応答イベントをリアルタイムに監視できます。

​
エラーレスポンス

HTTPtype説明
400invalid_request_errorevents が空、サポートされていないイベントタイプ、user.message の content 欠落、tool_use_id 欠落、custom_tool_use_id 欠落、無効な result、または形式エラー
401authentication_errorPAT が無効または期限切れ
404not_found_errorSession が存在しない
409conflict_errorprocessing 状態の Session にメッセージを送信した場合（先に現在のターンを cancel するか、idle に戻るのを待つ必要があります）

​
400 エラー例

{
  "error": {
    "message": "Field 'content' is required.",
    "type": "invalid_request_error"
  },
  "type": "error"
}

​
409 エラー例

{
  "error": {
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion.",
    "type": "conflict_error"
  },
  "type": "error"
}

​
関連項目

Session イベントストリーム

SSE で Agent の思考、メッセージ、ツール呼び出し、ステータスをストリーミング。