Copy

POST /api/v1/cloud/sessions Session を作成します。新しい Session は idle 状態で開始します。イベントを送信すると処理が始まります。

ヘッダー

ヘッダー	必須	説明
`Authorization`	はい	`Bearer <PAT または SAT>`
`Content-Type`	はい	`application/json`

リクエストボディ

フィールド	型	必須	説明
`agent`	string または object	はい	Agent ID、または `id`、必須の `type: "agent"`、任意の `version` を含むオブジェクト。Agent reference を参照
`environment_id`	string	はい	`env_` プレフィックスを持つ既存の Environment ID
`title`	string \| null	いいえ	Session タイトル
`metadata`	object	いいえ	Session メタデータ
`environment_variables`	object	いいえ	agent ランタイムに注入する Session レベルの環境変数。文字列キーから文字列値へのマップ（`{"NAME":"value"}`）として指定します。検証を参照。self-hosted 環境では非対応
`resources`	array	いいえ	作成時にアタッチする file、GitHub、汎用 Git、または Memory Store リソース
`vault_ids`	array	いいえ	Session が利用できる Vault ID

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 を返します。

リソースパラメータ

リソース種別	必須フィールド	任意フィールド
`file`	`type`, `file_id`	`mount_path`
`github_repository`	`type`, `url`	`authorization_token`, `mount_path`, `checkout`
`git_repository`	`type`, `url`	`password`, `mount_path`, `checkout`
`memory_store`	`type`, `memory_store_id`	`access`, `instructions`

github.com には github_repository を使用します。従来どおり、ユーザー名とトークンは任意です。GitLab、Gitee、Bitbucket など、その他の HTTP(S) Git サービスには git_repository を使用します。https://gitlab.com/group/repo.git のような公開リポジトリではユーザー名もパスワードも不要です。プライベートリポジトリへのアクセスまたは push を行う場合は、URL にプロバイダーのユーザー名を含め、password にアカウントのパスワードまたはプロバイダーが要求する Access Token/PAT を指定します。ユーザー名とパスワードは必ず両方指定してください。

{
  "type": "git_repository",
  "url": "https://username@gitlab.com/group/repo.git",
  "password": "<PASSWORD_OR_ACCESS_TOKEN>",
  "checkout": {"type": "branch", "name": "main"}
}

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"},
    "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"},
  "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",
  "usage": {"total_credits": 0}
}

エラー

HTTP	Type	発生条件
400	`invalid_request_error`	リクエストの形式エラー、必須フィールドの欠落、サポートされないフィールド、または無効なリソース
401	`authentication_error`	PAT または SAT が無効または期限切れ
404	`not_found_error`	Agent、Environment、file、Memory Store、または Vault が存在しない
409	`invalid_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 を環境で実行し、ステートフルな対話を行う。

Session の作成

ヘッダー

リクエストボディ

environment variables の検証

リソースパラメータ

リクエスト例

レスポンス例

エラー

関連項目

Session の起動

​ヘッダー

​リクエストボディ

​environment variables の検証

​リソースパラメータ

​リクエスト例

​レスポンス例

​エラー

​関連項目

Session の起動

ヘッダー

リクエストボディ

environment variables の検証

リソースパラメータ

リクエスト例

レスポンス例

エラー

関連項目