Session data structures

Session object

Returned by create, get, list, update, and archive endpoints.

Field	Type	Description
`id`	string	Session ID with the `sess_` prefix
`type`	string	Always `"session"`
`agent`	object	Agent snapshot used by this Session. See Session embedded agent for the field shape
`environment_id`	string	Environment ID used by this Session
`status`	string	Session lifecycle status: `rescheduling`, `running`, `idle`, or `terminated`. The `canceling` value in a Cancel endpoint response is a fixed acknowledgement value, not a persisted Session object status
`title`	string \| null	Session title
`metadata`	object	Session metadata
`environment_variables`	object	agent ランタイムに注入される Session レベルの環境変数。文字列キーから文字列値へのマップ（`{"NAME":"value"}`）として扱われ、空の Session では `{}` が返されます。Session の作成を参照してください
`resources`	array of Session resource	Session にアタッチされた file、GitHub、汎用 Git、または Memory Store リソース
`vault_ids`	array of string	Vault IDs attached to the Session
`deployment_id`	string \| null	Deployment ID when the Session was created by a Deployment, otherwise `null`
`outcome_evaluations`	array	Outcome evaluation results. New Sessions return `[]`
`stats`	Session stats	Session statistics
`usage`	Session usage	モデル、サンドボックス実行時間、合計 Credits の累積スナップショット。用量データがない場合は省略されます
`archived_at`	string \| null	Archive time, or `null` when not archived
`created_at`	string	Creation time
`updated_at`	string	Last update time

Session responses no longer include legacy fields such as agent_id, turn_status, or memory_store_ids.

Agent reference

agent in create requests can be either a string Agent ID or this object:

Field	Type	Required	Description
`id`	string	Yes	Agent ID with the `agent_` prefix
`type`	string	Yes (object form only)	Must be the literal `"agent"`. Missing or other values return 400 when the object form is used. The bare-string form (passing the Agent ID directly) skips this check
`version`	integer	No	Agent version to snapshot. Omit or pass `0` to use the latest active version

Session embedded agent

The agent returned inside a Session object is the Agent snapshot pinned to the Session, but several Agent fields are stripped before they are exposed: 新しいソース Agent 設定を公開しても、このスナップショットは置き換わりません。Session の更新で agent フィールドを送信すると、埋め込まれた agent.version を進めることなく、その Session のサポート対象のランタイムフィールドを変更できます。リンク先には Skill バージョンの動作も記載されています。

created_at, updated_at — never included on the embedded Agent.
archived, archived_at — never included; the Session preserves access to the snapshot regardless of the source Agent's archive state.
metadata — Agent-level metadata is stripped; only Session-level metadata is exposed.
instructions — replaced by system.

agent.multiagent.agents[] の応答構造は Multiagent roster element、各 Thread の Agent 構造は Session Thread objectを参照してください。

`agent.model.effective_context_window`

Sessions return an additional response-only effective_context_window (int64, in tokens) inside agent.model. It is the runtime-resolved context window the Session will use for this Agent (after applying environment-level overrides). Absent or non-positive values are omitted; clients should treat the field as informational.

Session resource

resources[] is a union distinguished by type.

File resource

Field	Type	Required	Description
`id`	string	Response only	Resource ID
`type`	string	Yes	`"file"`
`file_id`	string	Yes	File ID with the `file_` prefix. The file must be ready
`mount_path`	string	No	Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>` when omitted
`created_at`	string	Response only	Resource creation time
`updated_at`	string	Response only	Resource update time

GitHub repository resource

Field	Type	Required	Description
`id`	string	Response only	Resource ID
`type`	string	Yes	`"github_repository"`
`url`	string	Yes	Repository URL
`authorization_token`	string	いいえ（書き込み専用）	プライベートリポジトリへのアクセスまたは push に使用する GitHub トークン。レスポンスには返されません
`mount_path`	string	No	Clone target path in the container. Defaults from the repository name when omitted
`checkout`	object	No	Git checkout target, for example `{"type":"branch","name":"main"}`
`created_at`	string	Response only	Resource creation time
`updated_at`	string	Response only	Resource update time

汎用 Git repository resource

GitLab、Gitee、Bitbucket など、その他の HTTP(S) Git プロバイダーにはこのリソースを使用します。

フィールド	型	必須	説明
`id`	string	レスポンスのみ	Resource ID
`type`	string	はい	`"git_repository"`
`url`	string	はい	HTTP(S) clone URL。公開リポジトリではユーザー名は不要です。認証が必要なリポジトリでは、`https://username@gitlab.com/group/repo.git` のようにユーザー名を含めます
`password`	string	いいえ（書き込み専用）	プライベートリポジトリへのアクセスまたは push を行う場合、ユーザー名とともに指定します。アカウントのパスワードまたはプロバイダーが要求する Access Token/PAT を使用します。レスポンスには返されません
`mount_path`	string	いいえ	コンテナ内の clone 先。省略時はリポジトリ名から生成されます
`checkout`	object	いいえ	Git checkout 対象（例：`{"type":"branch","name":"main"}`）
`created_at`	string	レスポンスのみ	リソースの作成時刻
`updated_at`	string	レスポンスのみ	リソースの更新時刻

Memory Store resource

Field	Type	Required	Description
`type`	string	Yes	`"memory_store"`
`memory_store_id`	string	Yes	Memory Store ID with the `memstore_` prefix
`access`	string \| null	No	Optional access mode. Allowed values: `"read_write"`, `"read_only"`. Empty string or omitted means default (no override)
`instructions`	string \| null	No	Optional instructions stored on the Session resource. Maximum 4096 characters
`name`	string \| null	Response only	Current Memory Store name when available
`description`	string	Response only	Current Memory Store description when available
`mount_path`	string \| null	Response only	Current implementation returns `null` unless an existing resource snapshot contains a value

Memory Store resources do not include id, created_at, or updated_at fields.

Session stats

Field	Type	Description
`active_seconds`	number	Active processing time in seconds. New Sessions start at `0`
`duration_seconds`	number	Session duration in seconds. New Sessions start at `0`

Session usage

usage is the cumulative snapshot for a Session:

Field	Type	Description
`model_credits`	number	Session 内に記録されたモデル呼び出しの累積 Credits
`sandbox_runtime_credits`	number	Session が使用した課金対象のクラウドサンドボックス実行時間の累積 Credits
`total_credits`	number	すべての用量項目で累積した Credits の合計

用量データがない Session では usage が省略されます。3 つの Credits 値は四捨五入せず、小数点以下 2 桁まで切り捨てます。例えば 7.6681 は 7.66 になります。JSON の数値は末尾のゼロを保持しないため、1.20 が 1.2 と返される場合があります。3 フィールドを 1 回のスナップショットとして扱い、再取得時は Session ID ごとにローカル値を上書きしてください。繰り返し加算しないでください。

Multiagent roster element

Session 応答の agent.multiagent.agents[] では、通常の Agent と self エントリは対応する Agent 定義を以下のフィールドで返します。各エントリ自身の multiagent は含みません。 Advisor は type と model のみを返します。例：{"type":"advisor","model":"ultimate"}。Advisor オブジェクトを参照してください。

Field	Type	Description
`type`	string	`"agent"` for a sibling Agent reference, or `"self"` for the coordinator itself
`id`	string	Agent ID. Present for `type = "agent"`; mirrors the coordinator's own ID when `type = "self"`
`version`	integer	この Session が使用する子 Agent のバージョン。`type = "agent"` の場合に存在します。子 Agent が `"latest"` に設定され、Session 作成時の最新バージョンが v3 なら `3` を返し、この Session は引き続き v3 を使用します
`name`	string	Hydrated Agent name
`description`	string \| null	Hydrated Agent description
`system`	string	Hydrated Agent system prompt (replaces `instructions`)
`model`	string \| object	Same shape as on the embedded Agent, including `effective_context_window` when set
Other Agent fields	varies	Tools, MCP servers, skills, and other Agent fields, with the same field stripping rules as the embedded Agent

参照先 Agent の定義を取得できない場合（対象バージョンが存在しない場合など）、元の参照がそのまま返されます。

Event object

Events returned by send, list, and stream endpoints are event-specific JSON objects. Public event responses expose only the documented public fields for each event type.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`type`	string	Event type
`processed_at`	string	Present when the event has been processed. Many agent-generated events omit this field.

Depending on type, an event may also include fields such as content, input, name, tool_use_id, mcp_tool_use_id, custom_tool_use_id, result, deny_message, rubric, outcome_id, session_thread_id, stop_reason, error, usage, or model_usage.

Client event request types

POST /api/v1/cloud/sessions/{session_id}/events accepts exactly these client-sent event types:

Type	Required fields	Notes
`user.message`	`content`	`content` must be a non-empty array of content blocks
`user.interrupt`	none	`session_thread_id` is optional and is echoed as `null` when omitted
`user.tool_confirmation`	`tool_use_id`, `result`	`result` must be `allow` or `deny`; `deny_message` is optional
`user.tool_result`	`tool_use_id`	Use this to return a built-in tool result from a self-hosted worker. `content` is optional; when present, it must be an array of content blocks. `is_error` is optional
`user.custom_tool_result`	`custom_tool_use_id`	`content` is optional; when present, it must be an array of content blocks. `is_error` is optional
`user.define_outcome`	`description`, `rubric`	`rubric` is an object such as `{"type":"text","content":"..."}` or `{"type":"file","file_id":"file_..."}`; `max_iterations` is optional
`system.message`	`content`	`content` は空でないテキスト content block の配列である必要があります。user/tool result イベントの後に配置する必要があります

メッセージのコンテンツブロック

events[].type はイベントタイプ、content[].type はコンテンツブロックのタイプ、画像の source.type は画像の取得元を表します。

イベント	使用可能な `content[].type`	`content` の要件
`user.message`	`text`, `image`	必須の空でない配列。テキストと画像を混在できます
`system.message`	`text`	必須の空でない配列
`user.tool_result`, `user.custom_tool_result`	`text`, `image`, `document`, `search_result`	任意。指定する場合は配列である必要があり、空の配列も使用できます

ユーザーメッセージ

以下のフィールドはすべて必須です。選択したブロックタイプのフィールドのみを使用してください。

`content[].type`	フィールド	説明
`text`	`type`, `text`	`text` は空ではなく、空白文字のみでもない文字列である必要があります
`image`	`type`, `source`	`source` は以下の 3 つの形式のいずれかです

画像の source のフィールドはすべて文字列です。

`source.type`	必須フィールド	説明
`base64`	`type`, `media_type`, `data`	`media_type` は `image/png`、`image/jpeg`、`image/webp`、`image/gif` のいずれか。`data` は Data URL プレフィックスを含まない Base64 文字列で、末尾の `=` パディングは省略できます
`url`	`type`, `url`	モデルサービスが読み取れる外部 HTTPS 画像 URL。プライベート、ループバックなどの制限された宛先は拒否されます
`file`	`type`, `file_id`	ファイルをアップロードで取得した画像の File ID。現在の Identity が読み取り可能で、ステータスが `ready` である必要があります。PNG、JPEG、WebP、GIF に対応しています

画像の制限：

各 user.message には最大 100 個の画像ブロックを指定できます。Session には画像入力に対応したモデルを使用してください。
各 Base64 のエンコード済みテキストは最大 10 MiB（10,485,760 バイト）、画像の幅と高さはそれぞれ最大 8000 ピクセルです。エンコード後の長さが上限を超える場合は File を使用してください。
Base64 と File の画像はリサイズまたは圧縮される場合があります。URL の画像は下流のモデルサービスが取得します。

ユーザーメッセージの例

各例は単一のイベントオブジェクトです。送信時は events 配列に格納してください。テキスト：

{
  "type": "user.message",
  "content": [{"type": "text", "text": "こんにちは"}]
}

Base64 画像：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<画像の Base64 文字列>"}}]
}

URL 画像：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}}]
}

File 画像：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "file", "file_id": "file_..."}}]
}

エンドポイントについてはイベントを送信を参照してください。

Public event types

List and stream endpoints can expose these event types: user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result, user.define_outcome, user.tool_result, system.message, agent.artifact_delivered, agent.custom_tool_use, agent.mcp_tool_result, agent.mcp_tool_use, agent.message, agent.thinking, agent.thread_context_compacted, agent.thread_message_received, agent.thread_message_sent, agent.tool_result, agent.tool_use, session.deleted, session.error, session.status_idle, session.status_rescheduled, session.status_running, session.status_terminated, session.thread_created, session.thread_status_idle, session.thread_status_rescheduled, session.thread_status_running, session.thread_status_terminated, session.updated, span.model_request_start, span.model_request_end, span.outcome_evaluation_start, span.outcome_evaluation_ongoing, and span.outcome_evaluation_end.

`agent.artifact_delivered` イベント

agent.artifact_delivered は、Agent が成果物ファイルを正常に配信したことを示します。正常に配信されたファイルごとに 1 件のイベントが生成され、複数のファイルを配信した場合は複数のイベントが生成されます。このイベントはサーバーが生成し、イベントの一覧取得およびストリームのエンドポイントで取得できます。イベント送信エンドポイントから送信することはできません。

フィールド	型	説明
`id`	string	`evt_` プレフィックスを持つイベント ID
`type`	string	常に `agent.artifact_delivered`
`file_id`	string	配信されたファイルの ID。プレフィックスは `file_`
`original_filename`	string	配信されたファイルの元のファイル名
`size`	integer (int64)	ファイルサイズ（バイト単位）
`content_type`	string	ファイルの MIME タイプ（例：`application/pdf`）
`processed_at`	string	任意のイベント処理時刻。RFC 3339 形式

{
  "id": "evt_019e392c0d787cfaa21bda98e06cd914",
  "type": "agent.artifact_delivered",
  "file_id": "file_019e3bb9b0c2752688aeb5fdacf00565",
  "original_filename": "report.pdf",
  "size": 1234,
  "content_type": "application/pdf",
  "processed_at": "2026-05-18T03:40:50Z"
}

イベントを受信したら、file_id を使用してファイルの詳細を取得します。ファイルの downloadable が true の場合は、ファイルの内容をダウンロード（GET /api/v1/cloud/files/{file_id}/content）を呼び出して一時ダウンロード URL を取得し、その URL にリクエストしてファイルをダウンロードします。イベント自体にはファイルの内容もダウンロード URL も含まれません。

`session.updated` イベント

Session の更新が成功すると session.updated が発行されます。イベントには常に id、type、processed_at が含まれ、リクエストに応じて次のフィールドも含まれます。

フィールド	型	説明
`title`	string \| null	リクエストで `title` が指定された場合に含まれます
`metadata`	object	リクエストで `metadata` が指定され、結果の metadata オブジェクトが空でない場合に含まれます
`agent`	object	Session の更新でランタイム設定を変更した後の、更新済み埋め込みランタイムスナップショット

environment_variables だけを変更する更新では、固定フィールドのみが発行されます。環境変数の名前と値はこのイベントに含まれません。

`session.error` event

session.error reports an error during Session execution. The event contains id, type, processed_at, and error. The error object has these fields:

Field	Type	Description
`type`	string	Error category. Clients should handle `unknown_error` and future types
`message`	string	Human-readable error description
`retry_status`	object	Retry state. Its `type` is `retrying`, `exhausted`, or `terminal`
`qoder_error_code`	string	Optional diagnostic code. Clients must not use it to decide whether to retry

retry_status.type has these meanings:

Value	Description
`retrying`	The service is retrying automatically; the client should continue waiting
`exhausted`	再試行回数または復旧時間の上限に達したか、再試行できないエラーで直ちに失敗しました。このターンでは自動復旧を行いません。新しいメッセージを送るかどうかは後続の状態イベントを待って判断してください
`terminal`	The error is not recoverable and will not be retried automatically. Use subsequent Session/Thread status events to determine the final state

Advisor events

Advisor のライフサイクルイベントは agent_name: "qoder.advisor" で識別できます。相談ごとの識別には session_thread_id を使用します。

イベント	取得先	主なフィールド
`agent.thread_message_received`	メインスレッドのイベントストリーム	`from_session_thread_id` は相談 Thread、`from_agent_name` は `qoder.advisor`、`content` は助言内容
`agent.thread_message_sent`	Advisor Thread のイベントストリーム	`to_session_thread_id` と `to_agent_name` はメインスレッド、`content` は助言内容
`session.error`	Advisor Thread のイベントストリーム	`error` は原因と再試行状態。session.error eventを参照
`session.thread_status_idle`	Session のイベントストリーム	`stop_reason.type` は相談終了（中断を含む）時に `end_turn`、失敗時に `retries_exhausted`。原因は対象 Thread の `session.error` を参照

メインスレッドが助言を受信する例：

{
  "id": "evt_advisor_received",
  "type": "agent.thread_message_received",
  "processed_at": "2026-09-09T08:00:05Z",
  "from_session_thread_id": "sthr_advisor_call",
  "from_agent_name": "qoder.advisor",
  "content": [{"type": "text", "text": "カナリアリリースで移行し、ロールバック手順を検証してください。"}]
}

相談の失敗はメイン Agent のタスクを停止せず、助言メッセージも生成しません。エラーの詳細は Thread イベントのエンドポイントから取得してください。

Event delta stream frames

A buffered event is a complete public Event object emitted after generation finishes and recorded in Session event history. It is the authoritative result. event_start and event_delta are stream-only SSE payloads used for incremental output. They are not public Event objects and do not appear in event list/history responses. Their JSON payloads have no top-level id or processed_at; the SSE id: field carries the ID of the event being streamed and can be used with Last-Event-ID.

Event start frame

An event_start frame identifies the public event whose incremental output has begun.

Field	Type	Description
`type`	string	Always `"event_start"`
`event`	object	Streamed event reference

The event object has these fields:

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix. The SSE `id:`, related deltas, and buffered event use this same ID.
`type`	string	`"agent.message"` or `"agent.thinking"`

An agent.message start is followed by text event_delta frames. An agent.thinking start is start-only: no delta follows, and the buffered agent.thinking event with the same ID marks the end of that thinking phase when one is emitted.

{
  "type": "event_start",
  "event": {
    "id": "evt_00jjujk9fbnr4wkj2gh8",
    "type": "agent.message"
  }
}

Event delta frame

An event_delta frame appends text to an incrementally streamed agent.message.

Field	Type	Description
`type`	string	Always `"event_delta"`
`event_id`	string	ID from the matching `event_start.event.id` and SSE `id:` field
`delta`	object	Content delta

The delta object has these fields:

Field	Type	Description
`type`	string	Always `"content_delta"`
`index`	integer	Zero-based index of the content block being updated
`content`	object	Text fragment with `type: "text"` and a `text` string

{
  "type": "event_delta",
  "event_id": "evt_00jjujk9fbnr4wkj2gh8",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Hello"
    }
  }
}

Model request span events

span.model_request_start marks the beginning of one model request.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`processed_at`	string	RFC 3339 timestamp
`type`	string	Always `"span.model_request_start"`

span.model_request_end marks completion of that model request and includes model_usage when credits are available for the call. model_usage.credits is floored to at most 2 decimal places.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`is_error`	boolean	Whether the model request ended with an error or cancellation
`model_request_start_id`	string	ID of the corresponding `span.model_request_start` event
`model_usage`	object	Optional usage for this model call. Omitted when credits are unavailable
`processed_at`	string	RFC 3339 timestamp
`type`	string	Always `"span.model_request_end"`

model_usage contains only:

Field	Type	Description
`credits`	number	Credits consumed by this model call. The value may be `0` and is floored to at most 2 decimal places

Session Thread object

In managed-agent scenarios, each thread within a Session is represented by this structure.

Field	Type	Description
`id`	string	Thread ID with the `sthr_` prefix
`type`	string	Always `"session_thread"`
`session_id`	string	Owning Session ID
`parent_thread_id`	string \| null	Parent thread ID. `null` for the coordinator thread
`agent`	object	通常の Thread は Session embedded agent から `multiagent` を除いた構造を使用します。Advisor Thread は `{"type":"advisor","model":"..."}` を使用します
`status`	string	Thread lifecycle status: `running`, `idle`, `rescheduling`, or `terminated`
`stats`	object \| null	Thread statistics. Current implementation returns `null`
`archived_at`	string \| null	Archive time, or `null` when not archived
`created_at`	string	Creation time
`updated_at`	string	Last update time

Thread responses no longer include legacy fields such as agent_id, agent_version, name, role, stop_reason, created_by_tool_use_id, or usage.

​Session object

​Agent reference

​Session embedded agent

​agent.model.effective_context_window

​Session resource

​File resource

​GitHub repository resource

​汎用 Git repository resource

​Memory Store resource

​Session stats

​Session usage

​Multiagent roster element

​Event object

​Client event request types

​メッセージのコンテンツブロック

​ユーザーメッセージ

​ユーザーメッセージの例

​Public event types

​agent.artifact_delivered イベント

​session.updated イベント

​session.error event

​Advisor events

​Event delta stream frames

​Event start frame

​Event delta frame

​Model request span events

​Session Thread object