Create a deployment

Create a new Deployment that runs an Agent on a cron schedule or manually.

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.

Related

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.