Create a deployment

POST /api/v1/cloud/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. Object form must include `type: "agent"`.
`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 string key-value metadata (max 16 keys, key ≤64 chars, value ≤512 chars). Values must be strings.
`environment_variables`	string	No	Deployment-level environment variables to inject into sessions created by this deployment, formatted as `KEY=VALUE` pairs separated by `;` or newlines. Not supported on self-hosted environments.

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"`)

Environment variables

environment_variables uses the same validation as Session creation: variable names must match [A-Za-z_][A-Za-z0-9_]*, reserved names/prefixes are rejected, duplicate keys are rejected, and the total payload is limited. The response returns a normalized string sorted by key and joined with newlines.

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": [
          {
            "type": "text",
            "text": "Generate today'\''s status report"
          }
        ]
      }
    ],
    "resources": [],
    "vault_ids": [],
    "metadata": {
      "team": "platform"
    },
    "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=info"
  }'

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",
  "environment_variables": "FEATURE_FLAG=on\nLOG_LEVEL=info",
  "id": "dep_019ec556114c78f8b60ee34fcb98bf59",
  "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: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 or null	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	Custom string key-value metadata
`environment_variables`	string	Normalized `KEY=VALUE` lines injected into sessions created by this deployment
`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).
environment_variables is a Qoder extension on deployments. It is stored on the deployment template and copied into sessions created by deployment runs.
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, object-form `agent` without `type: "agent"`, invalid cron expression, invalid metadata or environment variables, 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

​Environment variables

​Example request

​Example response

​Response fields

​CMA alignment

​Errors

​Related