Update a deployment

Partially update an existing deployment using merge-patch semantics.

POST /api/v1/cloud/deployments/{id}

Updates a deployment with merge-patch semantics. Only fields included in the request body are modified; omitted fields retain their current values.

This endpoint uses POST (not PATCH) for CMA alignment. Only provided fields are applied as a partial update.

Path parameters

Parameter	Type	Description
id	string	Deployment ID with the dep_ prefix

Headers

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

Request body

All fields are optional. Only include fields you want to change.

Field	Type	Description
name	string	New name (max 256 characters)
description	string	New description
agent	string or object	New Agent reference (string ID or {id, type, version} object). Object form must include type: "agent".
environment_id	string	New Environment ID
schedule	object	Updated schedule config (must include all sub-fields: type, expression, timezone)
initial_events	array	New initial events array (1–50 events)
resources	array	Updated resources
vault_ids	array	Updated vault IDs
metadata	object or null	Merge-patch string metadata. String values upsert keys, key null deletes a key, and metadata: null clears all metadata.
environment_variables	string or null	Replacement deployment-level environment variables. null clears existing variables. Not supported on self-hosted environments.

Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/deployments/dep_019ec556114c78f8b60ee34fcb98bf59" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-doc-verification-deployment-v2",
    "schedule": {
      "type": "cron",
      "expression": "30 9 * * 1-5",
      "timezone": "Asia/Shanghai"
    }
  }'

Example response

HTTP 200 OK

Returns the full updated Deployment object.

{
  "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": "",
  "id": "dep_019ec556114c78f8b60ee34fcb98bf59",
  "initial_events": [
    {
      "content": [
        {
          "type": "text",
          "text": "Generate today's status report"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {},
  "name": "api-doc-verification-deployment-v2",
  "paused_reason": null,
  "resources": [],
  "schedule": {
    "expression": "30 9 * * 1-5",
    "timezone": "Asia/Shanghai",
    "type": "cron",
    "upcoming_runs_at": [
      "2026-06-15T01:30:00Z",
      "2026-06-16T01:30:00Z",
      "2026-06-17T01:30:00Z",
      "2026-06-18T01:30:00Z",
      "2026-06-19T01:30:00Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2026-06-14T08:54:05Z",
  "vault_ids": []
}

Errors

HTTP	Type	Trigger
400	invalid_request_error	Invalid field value, object-form agent without type: "agent", empty name, invalid cron expression, or referenced Agent/Environment is archived
401	authentication_error	PAT invalid or expired
404	not_found_error	Deployment does not exist

See Errors for the full error envelope.

Related

Get a deployment

Retrieve details for a single deployment.

Pause a deployment

Pause scheduling while preserving configuration.

Archive a deployment

Terminate the deployment and stop all scheduling.

Errors reference

All API error codes and the error envelope convention.