创建 Deployment

POST /api/v1/cloud/deployments 创建一个新的 Deployment。Deployment 将 Agent 绑定到 cron 调度（或纯手动触发）、一个 Environment 和一组初始事件。创建后状态为 active，如果配置了 schedule 会立即按计划执行。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT>`
`Content-Type`	是	`application/json`

请求体

字段	类型	必选	说明
`name`	string	是	Deployment 名称（最长 256 字符）
`description`	string	否	描述信息
`agent`	string 或 object	是	Agent 引用。纯字符串 `"agent_xxx"`（使用最新版本）或对象 `{"id": "agent_xxx", "type": "agent", "version": 2}`（锁定版本）。对象形式必须包含 `type: "agent"`。
`environment_id`	string	是	Environment ID（`env_` 前缀）
`schedule`	object	否	Cron 调度配置。不传则为纯手动触发（响应中 schedule 为 `null`）。见下方 Schedule 对象。
`initial_events`	array	是	每次运行时发送给 Agent 的事件数组（1–50 个）。每个事件必须含 `type` 字段。允许类型：`user.message`、`user.define_outcome`、`system.message`。
`resources`	array	否	附加到每次 session 的资源（如 `github_repository`、`file`、`memory_store`）。默认 `[]`。
`vault_ids`	array	否	注入凭据的 Vault ID 列表。默认 `[]`，最多 50 个。
`metadata`	object	否	自定义字符串键值元数据（最多 16 个 key，key ≤64 字符，value ≤512 字符）。value 必须是字符串。
`environment_variables`	string	否	Deployment 级环境变量，会注入到该 Deployment 创建的 Session 中。格式为以 `;` 或换行分隔的 `KEY=VALUE` 字符串。Self-hosted Environment 不支持。

Schedule 对象

字段	类型	必选	说明
`type`	string	是	必须为 `"cron"`
`expression`	string	是	标准 5 段 cron 表达式（如 `"0 9 * * *"`）
`timezone`	string	是	IANA 时区（如 `"Asia/Shanghai"`）

environment_variables 校验

environment_variables 复用创建 Session 的校验规则：变量名必须匹配 [A-Za-z_][A-Za-z0-9_]*，保留名称/前缀会被拒绝，重复 key 会被拒绝，并受总大小限制。响应会返回按 key 排序并以换行连接的规范化字符串。

示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/deployments" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-doc-verification-deployment",
    "description": "Deployment created for API documentation verification",
    "agent": "agent_019ebb21ef8e7df6a559052c94875160",
    "environment_id": "env_019e49a1780171daac1e6b01f290ac2b",
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * *",
      "timezone": "Asia/Shanghai"
    },
    "initial_events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Generate today'\''s status report"
          }
        ]
      }
    ],
    "resources": [],
    "vault_ids": [],
    "metadata": {
      "team": "platform"
    },
    "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=info"
  }'

示例响应

HTTP 200 OK

{
  "agent": {
    "id": "agent_019ebb21ef8e7df6a559052c94875160",
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-06-14T08:58:01Z",
  "description": "Deployment created for API documentation verification",
  "environment_id": "env_019e49a1780171daac1e6b01f290ac2b",
  "environment_variables": "FEATURE_FLAG=on\nLOG_LEVEL=info",
  "id": "dep_019ec55a2b687b3f94eee77dd77e4b2a",
  "initial_events": [
    {
      "content": [
        {
          "type": "text",
          "text": "Generate today's status report"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "team": "platform"
  },
  "name": "api-doc-verification-deployment",
  "paused_reason": null,
  "resources": [],
  "schedule": {
    "expression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "type": "cron",
    "upcoming_runs_at": [
      "2026-06-15T01:00:00Z",
      "2026-06-16T01:00:00Z",
      "2026-06-17T01:00:00Z",
      "2026-06-18T01:00:00Z",
      "2026-06-19T01:00:00Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2026-06-14T08:58:01Z",
  "vault_ids": []
}

响应字段

字段	类型	说明
`id`	string	Deployment 唯一标识（`dep_` 前缀）
`type`	string	固定值 `"deployment"`
`name`	string	Deployment 名称
`description`	string 或 null	描述
`agent`	object	Agent 引用：`{id, type, version}`
`environment_id`	string	关联的 Environment ID
`schedule`	object 或 null	调度配置，含 `upcoming_runs_at`（纯手动时为 null）
`schedule.expression`	string	Cron 表达式
`schedule.timezone`	string	IANA 时区
`schedule.type`	string	固定 `"cron"`
`schedule.upcoming_runs_at`	array	未来 5 次调度时间（UTC，ISO 8601）
`schedule.last_run_at`	string	上次执行时间（首次运行后出现）
`initial_events`	array	每次运行时发送的事件
`resources`	array	附加资源
`vault_ids`	array	关联的 Vault ID 列表
`metadata`	object	自定义字符串键值元数据
`environment_variables`	string	规范化后的 `KEY=VALUE` 行，会注入到该 Deployment 创建的 Session
`status`	string	`"active"` 或 `"paused"`
`paused_reason`	object 或 null	暂停原因（如 `{"type":"manual"}`）
`archived_at`	string 或 null	归档时间（ISO 8601）或 null
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	最后更新时间（ISO 8601）

CMA 对齐

本端点对齐 Anthropic CMA POST /v1/deployments 规范。主要差异：

agent 字段同时接受字符串和对象形式（CMA 仅要求对象形式）。
environment_variables 是 Qoder Deployment 扩展字段，会保存在 Deployment 模板上，并复制到 Deployment Run 创建的 Session。
响应中 schedule 对象含 upcoming_runs_at 字段（未来 5 次触发时间）。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少必填字段、对象形式 `agent` 缺少 `type: "agent"`、无效 cron 表达式、metadata 或 environment_variables 无效、未知事件类型，或引用的 Agent/Environment 已归档
401	`authentication_error`	PAT 无效或过期
404	`not_found_error`	Agent 或 Environment 不存在

完整错误信封说明详见错误参考。

列出 Deployment

分页查询账号下的所有 Deployment。

获取 Deployment

查看单个 Deployment 的详细信息。

更新 Deployment

修改名称、调度、资源等可变字段。

错误参考

所有 API 错误码与错误信封约定。

​请求头

​请求体

​Schedule 对象

​environment_variables 校验

​示例请求

​示例响应

​响应字段

​CMA 对齐

​错误码

​相关