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

​
请求头

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

​
请求体

字段类型必选说明
namestring是Deployment 名称（最长 256 字符）
descriptionstring否描述信息
agentstring 或 object是Agent 引用。纯字符串 "agent_xxx"（使用最新版本）或对象 {"id": "agent_xxx", "type": "agent", "version": 2}（锁定版本）。
environment_idstring是Environment ID（env_ 前缀）
scheduleobject否Cron 调度配置。不传则为纯手动触发（响应中 schedule 为 null）。见下方 Schedule 对象。
initial_eventsarray是每次运行时发送给 Agent 的事件数组（1–50 个）。每个事件必须含 type 字段。允许类型：user.message、user.define_outcome、system.message。
resourcesarray否附加到每次 session 的资源（如 github_repository、file、memory_store）。默认 []。
vault_idsarray否注入凭据的 Vault ID 列表。默认 []，最多 50 个。
metadataobject否自定义键值元数据（最多 16 个 key，key ≤64 字符，value ≤512 字符）。保留 key cas_config 不受限制，用于控制 CAS 执行参数。

​
Schedule 对象

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

​
metadata.cas_config（CAS 扩展）

metadata 中的 cas_config key 控制 CAS 特有的执行行为：
字段类型默认值说明
session_strategystring"new_session"Session 复用策略
config.max_retriesinteger0失败时最大重试次数
config.timeout_msinteger300000单次运行超时（毫秒）
config.max_concurrentinteger1最大并发运行数

​
示例请求

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": "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": []
}

​
响应字段

字段类型说明
idstringDeployment 唯一标识（dep_ 前缀）
typestring固定值 "deployment"
namestringDeployment 名称
descriptionstring描述
agentobjectAgent 引用：{id, type, version}
environment_idstring关联的 Environment ID
scheduleobject 或 null调度配置，含 upcoming_runs_at（纯手动时为 null）
schedule.expressionstringCron 表达式
schedule.timezonestringIANA 时区
schedule.typestring固定 "cron"
schedule.upcoming_runs_atarray未来 5 次调度时间（UTC，ISO 8601）
schedule.last_run_atstring上次执行时间（首次运行后出现）
initial_eventsarray每次运行时发送的事件
resourcesarray附加资源
vault_idsarray关联的 Vault ID 列表
metadataobject元数据，含 cas_config（执行配置和统计）
statusstring"active" 或 "paused"
paused_reasonobject 或 null暂停原因（如 {"type":"manual"}）
archived_atstring 或 null归档时间（ISO 8601）或 null
created_atstring创建时间（ISO 8601）
updated_atstring最后更新时间（ISO 8601）

​
CMA 对齐

本端点对齐 Anthropic CMA POST /v1/deployments 规范。主要差异：
  • agent 字段同时接受字符串和对象形式（CMA 仅要求对象形式）。
  • metadata.cas_config 是 CAS 扩展，用于执行参数调优（不在 CMA 规范中），含 session_strategy、config（重试/超时/并发）和 stats（运行统计）。
  • 响应中 schedule 对象含 upcoming_runs_at 字段（未来 5 次触发时间）。

​
错误码

HTTPtype触发条件
400invalid_request_error缺少必填字段、无效 cron 表达式、未知事件类型、或引用的 Agent/Environment 已归档
401authentication_errorPAT 无效或过期
404not_found_errorAgent 或 Environment 不存在
完整错误信封说明详见 错误参考。

​
相关

列出 Deployment

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

获取 Deployment

查看单个 Deployment 的详细信息。

更新 Deployment

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

错误参考

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