Skip to main content
Events

イベントの送信

Session に user または system イベントを送信します。

POST /api/v1/cloud/sessions/{session_id}/events 1 つ以上の受理可能なイベントを Session に送信します。user.message は非同期に Agent の処理をトリガーします。Agent の出力は list または stream エンドポイントで読み取ってください。

パスパラメータ

パラメータ型説明
session_idstringsess_ プレフィックス付きの Session ID

ヘッダー

ヘッダー必須説明
AuthorizationはいBearer $QODER_ACCESS_TOKEN
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 の配列である必要があります。各リクエストに最大 1 つ指定でき、バッチの最後のイベントとして、user.message、user.tool_result、user.custom_tool_result のいずれかの直後に配置する必要があります
文字列形式の events[].content はサポートされません。イベントに content フィールドがある場合は、content block の配列として送信してください。メッセージのコンテンツブロックに、各イベントで使用可能なブロックタイプとフィールドを示します。

リクエスト例

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

画像メッセージを送信する

以下の JSON リクエストボディは、3 種類の画像の取得元を示します。フィールドと制限についてはメッセージのコンテンツブロックを参照してください。

Base64 を直接指定する

data を画像の Base64 文字列に置き換えてください。data:image/png;base64, プレフィックスは含めず、media_type を画像形式に合わせてください。 
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {"type": "text", "text": "この画像を説明してください。"},
        {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<画像の Base64 文字列>"}}
      ]
    }
  ]
}

HTTPS 画像 URL を使用する

URL をモデルサービスが読み取れる外部 HTTPS 画像 URL に置き換えてください。 
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {"type": "text", "text": "この画像を説明してください。"},
        {"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}}
      ]
    }
  ]
}

アップロード済みの画像を参照する

ファイルをアップロードで、アクセス可能でステータスが ready の画像 File ID を取得してください。 
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {"type": "text", "text": "この画像を説明してください。"},
        {"type": "image", "source": {"type": "file", "file_id": "file_..."}}
      ]
    }
  ]
}

レスポンス例

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."
    }
  ]
}
self-hosted Environment では、worker が組み込みツールを実行した結果を user.tool_result で返します。tool_use_id には対応する agent.tool_use イベントの id を指定します。 
{
  "events": [
    {
      "type": "user.tool_result",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "content": [{"type": "text", "text": "Command completed successfully."}],
      "is_error": false
    }
  ]
}
ストリームが 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 または SAT が無効または期限切れ
404not_found_errorSession または保留中のアクションが存在しない
409invalid_request_errorSession が現在ターンを処理中、またはその他の Session 状態の競合（注意: type は conflict_error ではなく invalid_request_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 がターンを処理中

Session が running または rescheduling の間、新しい user.message は現在のターンの後ろにキューイングされず、409 を返します。session.status_idle を待つか、先に現在のターンをキャンセルしてください。 
{
  "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"
}
完全なエラーエンベロープについては エラー を参照してください。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス