Create a deployment

POST /v1/deployments Creates a new Deployment. A Deployment binds an Agent to a cron schedule (or manual-only trigger), an Environment, and an initial set of events delivered at each run. The newly created deployment is in the active status and will begin firing according to its schedule immediately.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $QODER_PAT`
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`name`	string	Yes	Deployment name (max 256 characters)
`description`	string	No	Human-readable description
`agent`	string or object	Yes	Agent reference. Either a plain string `"agent_xxx"` (uses latest version) or an object `{"id": "agent_xxx", "type": "agent", "version": 2}` to pin a specific version.
`environment_id`	string	Yes	Environment ID (`env_` prefix)
`schedule`	object	No	Cron schedule configuration. If omitted, the deployment is manual-only (schedule will be `null` in response). See Schedule object below.
`initial_events`	array	Yes	Array of events (1–50) delivered to the Agent on each run. Each event must have a `type` field. Allowed types: `user.message`, `user.define_outcome`, `system.message`.
`resources`	array	No	Resources attached to each session (e.g., `github_repository`, `file`, `memory_store`). Default `[]`.
`vault_ids`	array	No	List of Vault IDs to inject credentials. Default `[]`. Max 50.
`metadata`	object	No	Custom key-value metadata (max 16 keys, key ≤64 chars, value ≤512 chars). The reserved key `cas_config` is exempt from limits and controls CAS-specific execution parameters.

Schedule object

Field	Type	Required	Description
`type`	string	Yes	Must be `"cron"`
`expression`	string	Yes	Standard 5-field cron expression (e.g., `"0 9 * * *"`)
`timezone`	string	Yes	IANA timezone (e.g., `"Asia/Shanghai"`)

metadata.cas_config (CAS extension)

The cas_config key within metadata controls CAS-specific execution behavior:

Field	Type	Default	Description
`session_strategy`	string	`"new_session"`	Session reuse strategy
`config.max_retries`	integer	`0`	Max retry attempts on failure
`config.timeout_ms`	integer	`300000`	Run timeout in milliseconds
`config.max_concurrent`	integer	`1`	Max concurrent runs

Example request

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_019eb4d4a06d747c865d5800b9c57ae2",
    "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * *",
      "timezone": "Asia/Shanghai"
    },
    "initial_events": [
      {"type": "user.message", "content": "Generate today'\''s status report"}
    ],
    "resources": [],
    "vault_ids": [],
    "metadata": {}
  }'

Example response

HTTP 200 OK

{
  "agent": {
    "id": "agent_019eb4d4a06d747c865d5800b9c57ae2",
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-06-14T08:53:32Z",
  "description": "Deployment created for API documentation verification",
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "id": "dep_019ec556114c78f8b60ee34fcb98bf59",
  "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:53:32Z",
  "vault_ids": []
}

Response fields

Field	Type	Description
`id`	string	Deployment unique identifier (`dep_` prefix)
`type`	string	Always `"deployment"`
`name`	string	Deployment name
`description`	string	Description
`agent`	object	Agent reference: `{id, type, version}`
`environment_id`	string	Associated Environment ID
`schedule`	object or null	Schedule config with `upcoming_runs_at` (null for manual-only)
`schedule.expression`	string	Cron expression
`schedule.timezone`	string	IANA timezone
`schedule.type`	string	Always `"cron"`
`schedule.upcoming_runs_at`	array	Next 5 scheduled fire times (UTC, ISO 8601)
`schedule.last_run_at`	string	Last execution time (appears after first run)
`initial_events`	array	Events delivered on each run
`resources`	array	Attached resources
`vault_ids`	array	Associated Vault IDs
`metadata`	object	Metadata including `cas_config` with execution config and stats
`status`	string	`"active"` or `"paused"`
`paused_reason`	object or null	Structured pause reason (e.g., `{"type":"manual"}`)
`archived_at`	string or null	Archive timestamp (ISO 8601) or null
`created_at`	string	Creation time (ISO 8601)
`updated_at`	string	Last update time (ISO 8601)

CMA alignment

This endpoint aligns with the Anthropic CMA POST /v1/deployments spec. Key differences:

The agent field accepts both string and object forms (CMA requires object only).
metadata.cas_config is a CAS extension for execution tuning (not in CMA spec), containing session_strategy, config (retries/timeout/concurrency), and stats (run counts/timestamps).
Response includes upcoming_runs_at in the schedule object (up to 5 future fire times).

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Missing required field, invalid cron expression, unknown event type, or referenced Agent/Environment is archived
401	`authentication_error`	PAT invalid or expired
404	`not_found_error`	Agent or Environment does not exist

See Errors for the full error envelope.

List deployments

Page through all deployments under the account.

Get a deployment

Retrieve details for a single deployment.

Update a deployment

Modify name, schedule, resources, and other mutable fields.

Errors reference

All API error codes and the error envelope convention.

​Headers

​Request body

​Schedule object

​metadata.cas_config (CAS extension)

​Example request

​Example response

​Response fields

​CMA alignment

​Errors

​Related