メインコンテンツへスキップ
POST /api/v1/cloud/sessions Session を作成します。新しい Session は idle 状態で開始します。イベントを送信すると処理が始まります。

​
ヘッダー

ヘッダー必須説明
AuthorizationはいBearer $QODER_PAT
Content-Typeはいapplication/json

​
リクエストボディ

フィールド型必須説明
agentstring または objectはいAgent ID、または id、必須の type: "agent"、任意の version を含むオブジェクト。Agent reference を参照
environment_idstringはいenv_ プレフィックスを持つ既存の Environment ID
titlestring | nullいいえSession タイトル
metadataobjectいいえSession メタデータ
environment_variablesstringいいえagent ランタイムに注入する Session レベルの環境変数。KEY=VALUE ペアを ;(または改行、全角 ; も受け付け)で区切った単一文字列で指定します。レスポンスのフィールドは JSON オブジェクトです — 検証 を参照。self-hosted 環境では非対応
incremental_streaming_enabledbooleanいいえこの Session の増分ストリーミングイベントを有効にします。デフォルト: false。true の場合、list および stream のイベント API は、最終的な完全イベントに加えて agent.message_start、agent.content_block_delta、agent.message_stop などの増分 agent イベントを公開します
resourcesarrayいいえ作成時にアタッチする file、GitHub リポジトリ、または Memory Store リソース
vault_idsarrayいいえSession が利用できる Vault ID
レガシーリクエストフィールド environment、delta_flush_interval_ms、vaults、memory_store_ids はサポートされません。Memory Store をアタッチするには resources[] で type: "memory_store" を使用してください。

​
environment variables の検証

名前は [A-Za-z_][A-Za-z0-9_]* に一致する必要があります。予約名 SERVER_ENDPOINT、USER_ID、WORK_DIR、および CAW_ または QODER_ プレフィックスを持つ名前は拒否されます。各値は 8 KiB を超えられません。フィールド全体で 64 エントリまたは合計 64 KiB を超えられません。重複キー、不正な形式のエントリ、または self-hosted 環境での使用は 400 invalid_request_error を返します。

​
リソースパラメータ

リソース種別必須フィールド任意フィールド
filetype, file_idmount_path
github_repositorytype, url, authorization_tokenmount_path, checkout
memory_storetype, memory_store_idaccess, instructions
self-hosted 環境は現在 Session resources をサポートしていません。

​
リクエスト例

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", "type": "agent", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "Code review session",
    "metadata": {"purpose": "review"},
    "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=debug",
    "incremental_streaming_enabled": true,
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo",
        "mount_path": "/data/workspace/your-repo",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019eed05b61e78cea61bfd366e072878",
        "access": "read_write",
        "instructions": "Use this memory for long-lived project context."
      }
    ],
    "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"]
  }'

​
レスポンス例

HTTP 200 OK Session オブジェクトを返します。 
{
  "id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
  "type": "session",
  "agent": {
    "id": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "type": "agent",
    "name": "doc-test-agent",
    "description": "Documentation example Agent",
    "model": {
      "id": "ultimate",
      "effective_context_window": 200000
    },
    "system": "You are a test assistant.",
    "tools": [],
    "skills": [],
    "mcp_servers": [],
    "version": 2
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "Code review session",
  "status": "idle",
  "metadata": {"purpose": "review"},
  "environment_variables": {"FEATURE_FLAG": "on", "LOG_LEVEL": "debug"},
  "incremental_streaming_enabled": true,
  "resources": [],
  "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"],
  "deployment_id": null,
  "outcome_evaluations": [],
  "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"
}

​
エラー

HTTPType発生条件
400invalid_request_errorリクエストの形式エラー、必須フィールドの欠落、サポートされないレガシーフィールド、または無効なリソース
401authentication_errorPAT が無効または期限切れ
404not_found_errorAgent、Environment、file、Memory Store、または Vault が存在しない
409invalid_request_error参照したファイルが ready でない、またはリソースのパス/ID が競合
HTTP 400 Bad Request 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'agent' is required."
  }
}
HTTP 404 Not Found 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent 'agent_does_not_exist_0000000000000000000000000000' was not found."
  }
}
注意: agent_ プレフィックスを持たない agent 値(または env_ プレフィックスを持たない environment_id)も、400 ではなく 404 not_found_error として解決されます。 完全なエラーエンベロープについては Errors を参照してください。

​
関連項目

Session の起動

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