创建 Deployment（cron/手动）

请求头

头部	必选	说明
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}（锁定版本）。
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 字符）。保留 key cas_config 不受限制，用于控制 CAS 执行参数。

Schedule 对象

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

metadata.cas_config（CAS 扩展）

metadata 中的 cas_config key 控制 CAS 特有的执行行为：

字段	类型	默认值	说明
session_strategy	string	"new_session"	Session 复用策略
config.max_retries	integer	0	失败时最大重试次数
config.timeout_ms	integer	300000	单次运行超时（毫秒）
config.max_concurrent	integer	1	最大并发运行数

示例请求

curl -X POST "https://api.qoder.com.cn/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": "Generate today'\''s status report"}
    ],
    "resources": [],
    "vault_ids": [],
    "metadata": {}
  }'

示例响应

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",
  "id": "dep_019ec55a2b687b3f94eee77dd77e4b2a",
  "initial_events": [
    {
      "content": "Generate today's status report",
      "type": "user.message"
    }
  ],
  "metadata": {
    "cas_config": {
      "config": {
        "max_concurrent": 1,
        "max_retries": 0,
        "timeout_ms": 300000
      },
      "session_strategy": "new_session",
      "stats": {
        "consecutive_failures": 0,
        "next_trigger_at": "2026-06-15T01:00:00Z",
        "total_failures": 0,
        "total_runs": 0
      }
    }
  },
  "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	描述
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	元数据，含 cas_config（执行配置和统计）
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 仅要求对象形式）。

• metadata.cas_config 是 CAS 扩展，用于执行参数调优（不在 CMA 规范中），含 session_strategy、config（重试/超时/并发）和 stats（运行统计）。

• 响应中 schedule 对象含 upcoming_runs_at 字段（未来 5 次触发时间）。

错误码

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

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