创建 Session

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 引用
`environment_id`	string	是	`env_` 前缀的已有 Environment ID
`budget`	object \| null	否	会话总预算（含模型和沙箱费用），如 `{"type":"limit","max_credit_cost":"100.00"}`。省略则不设置预算；`null` 同样表示不设上限。详见 Session budget
`title`	string \| null	否	Session 标题
`metadata`	object	否	Session 元数据
`environment_variables`	object	否	注入到 agent 运行时的 Session 级环境变量，以字符串 key 到字符串 value 的 map（`{"NAME":"value"}`）传入。详见校验规则。Self-hosted Environment 不支持
`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_]*，且所有 value 必须是字符串；保留名 SERVER_ENDPOINT、USER_ID、WORK_DIR，以及任何带 CAW_、QODER_ 前缀的名称都会被拒绝。单个 value 不超过 8 KiB；整个 map 不超过 64 条且总字节不超过 64 KiB。key 或 value 非法，或在 self-hosted Environment 上使用，会返回 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，继续保持原有的用户名和 Token 可选逻辑。GitLab、Gitee、Bitbucket 及其他 HTTP(S) Git 服务使用 git_repository。公开仓库无需用户名和密码，例如 https://gitlab.com/group/repo.git；私有仓库或需要推送时，请在 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 Environment 当前不支持 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": {"model_credits": 0, "sandbox_runtime_credits": 0, "total_credits": 0}
}

错误码

HTTP	类型	触发条件
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_ 前缀（或 environment_id 缺少 env_ 前缀）时同样会被解析为 404 not_found_error，而不是 400。详见 Errors。

启动 Session

让 Agent 在环境中以有状态对话的方式运行。

​请求头

​请求体

​environment_variables 校验

​资源参数

​示例请求

​示例响应

​错误码

​相关

启动 Session

请求头

请求体

environment_variables 校验

资源参数

示例请求

示例响应

错误码

相关