メインコンテンツへスキップ
POST /v1/sessions 新しい Session を作成します。Session は Agent とユーザー間の対話コンテナです。作成直後の状態は idle で、Events API でメッセージを送信することで Agent の処理がトリガーされます。

​
ヘッダー

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

​
リクエストボディ

フィールド型必須説明
agentstring or objectはいAgent 参照。文字列の Agent ID を渡すと最新のアクティブバージョンを使用します。またはオブジェクトで id、任意の type、任意の version を指定します。
environment_idstring条件付き既存の Environment ID（env_ プレフィックス）。environment を指定しない場合は必須。両方指定した場合は environment_id が優先されます。
environmentstring or object条件付き文字列の既存 Environment ID、またはインライン Environment オブジェクト。environment_id を指定しない場合は必須。
titlestringいいえSession タイトル
metadataobjectいいえカスタムメタデータのキーバリュー
delta_flush_interval_msintegerいいえ増分フラッシュ間隔（ミリ秒）。範囲 50-5000、デフォルト 100
memory_store_idsarrayいいえ一意かつ空でない Memory Store ID の配列。デフォルトは []
resourcesarrayいいえファイルまたは GitHub リポジトリリソースのリスト。デフォルトは []
vault_idsarrayいいえ一意かつ空でない Vault ID の配列。デフォルトは []
vaultsarrayいいえvault_ids のエイリアス。vault_ids が省略または空の場合にのみ使用されます。
environment_variablesstringいいえSession スコープの環境変数。セミコロンまたは改行で区切った KEY=VALUE 文字列。デフォルトはカスタム変数なし。self-hosted 環境では非対応。

​
agent オブジェクト

フィールド型必須説明
idstringはいAgent ID（agent_ プレフィックス）
typestringいいえ任意のタイプマーカー。サーバーは特定の値を要求しません。
versionintegerいいえこの Session にスナップショットする Agent バージョン。省略または 0 を渡すと最新のアクティブ Agent を使用します。

​
インライン environment オブジェクト

フィールド型必須説明
namestringいいえEnvironment 名。省略または空の場合、デフォルトは "Session Environment"
descriptionstringいいえEnvironment の説明
configobjectはいEnvironment 設定。Environment の作成 と同じスキーマです。
metadataobjectいいえインライン Environment のカスタムメタデータ

​
environment_variables 形式

environment_variables は JSON オブジェクトではなく単一の文字列として渡します。エントリはセミコロンまたは改行で区切ります： 
{
  "environment_variables": "NODE_ENV=production; FEATURE_FLAG=1\nEMPTY_VALUE="
}
各エントリは KEY=VALUE 形式で記述します。名前は [A-Za-z_][A-Za-z0-9_]* に一致する必要があり、重複名は拒否され、空の値は許可されます。サーバーは最大 64 個の変数、1 値あたり最大 8 KiB、名前と値の合計で最大 64 KiB を受け付けます。SERVER_ENDPOINT、USER_ID、WORK_DIR の名称および CAW_、QODER_ のプレフィックスは予約済みです。

​
resources 配列要素

resources 配列の各要素は type フィールドで区別されます： ファイルリソース (type: "file")：
フィールド型必須説明
typestringいいえ"file"。省略時のデフォルトは "file" です。
file_idstringはいファイル ID（Files API でアップロード後に取得）。ファイルは ready ステータスである必要があります。
pathstringいいえマウントパス。デフォルトは /data/{file_id}。相対パスの場合、サーバーが /data/ プレフィックスを付与します。正規化されたパスは /data/ 配下かつ最大 512 文字である必要があります。
mount_pathstringいいえpath のエイリアス。path と mount_path の両方を指定する場合、値が同一である必要があります。レスポンスでは正規化された値が path として格納されます。
GitHub リポジトリリソース (type: "github_repository")：
フィールド型必須説明
typestringはい"github_repository"
urlstringはいリポジトリ URL
mount_pathstringいいえコンテナ内のクローン先パス
authorization_tokenstringいいえプライベートリポジトリアクセス用の認可トークン。指定した場合、Session リソースオブジェクトに格納されます。

​
リクエスト例

curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e390add9f7bac9b6cc806db46fcbd", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "私の Session",
    "metadata": {"purpose": "customer-support"},
    "environment_variables": "NODE_ENV=production; FEATURE_FLAG=1",
    "delta_flush_interval_ms": 100
  }'

​
GitHub リポジトリ付きの例

curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e390add9f7bac9b6cc806db46fcbd", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "コードレビュー Session",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo"
      }
    ]
  }'

​
レスポンス例

HTTP 201 Created 完全な Session オブジェクトを返します。 
{
  "id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
  "type": "session",
  "agent_id": "agent_019e390add9f7bac9b6cc806db46fcbd",
  "agent": {
    "id": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "type": "agent",
    "name": "doc-test-agent",
    "description": "ドキュメント例示用 Agent",
    "model": "ultimate",
    "system": "あなたはテストアシスタントです",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "skills": [],
    "metadata": {},
    "mcp_servers": [
      {
        "type": "http",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ],
    "version": 2,
    "archived_at": null,
    "created_at": "2026-05-18T03:04:33.952256Z",
    "updated_at": "2026-05-18T03:05:28.023697Z"
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "私の Session",
  "status": "idle",
  "turn_status": "idle",
  "metadata": {"purpose": "customer-support"},
  "resources": [],
  "vault_ids": [],
  "memory_store_ids": [],
  "environment_variables": {
    "NODE_ENV": "production",
    "FEATURE_FLAG": "1"
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "archived_at": null,
  "created_at": "2026-05-18T15:26:15.747298Z",
  "updated_at": "2026-05-18T15:26:15.747298Z"
}

​
Session オブジェクトのフィールド

フィールド型説明
idstringSession の一意識別子（sess_ プレフィックス）
typestring固定値 "session"
agent_idstring関連付けられた Agent ID
agentobjectこの Session 用にキャプチャされた Agent スナップショット。Agent レスポンス形式を使用します：id、type、name、description、model、system、tools、mcp_servers、skills、metadata、version、nullable archived_at、created_at、updated_at。instructions や default_environment は返しません。
environment_idstring関連付けられた Environment ID
titlestringSession タイトル
statusstringSession ライフサイクル状態。新しい Session は "idle" で開始し、アクティブなターンでは通常 "running" になります。
turn_statusstring現在のターン状態。"idle"、"processing"、"cancelling" など。
metadataobjectSession メタデータ
resourcesarray正規化されたリソースオブジェクト。ファイルリソースには type、file_id、path が含まれ、GitHub リポジトリリソースには type、url、任意の mount_path、任意の authorization_token が含まれます。
vault_idsarray関連付けられた Vault ID
memory_store_idsarray関連付けられた Memory Store ID
environment_variablesobject正規化後の Session スコープ環境変数。カスタム変数が指定されていない場合は空のオブジェクト。
statsobjectSession 統計。新規作成時は active_seconds と duration_seconds が共に 0 です。
archived_atstring or nullアーカイブ時刻。Session がアーカイブされるまで null。
created_atstring作成時刻（ISO 8601）
updated_atstring最終更新時刻（ISO 8601）

​
エラーレスポンス

HTTPtype説明
400invalid_request_errorリクエストボディの形式エラー、必須フィールド欠落、または environment_variables の形式が不正
401authentication_errorPAT が無効または期限切れ
404not_found_errorAgent または Environment が存在しない
409conflict_error参照先の Environment がアーカイブ済み、ファイルリソースが ready でない、またはリソースのパス/ID が競合

​
関連項目

Session の起動

Agent を環境で実行し、ステートフルな対話を行う。