> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```bash theme={null} 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** ```json theme={null} { "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](/cloud-agents/api/conventions/errors) for the full error envelope. ## Related Page through all deployments under the account. Retrieve details for a single deployment. Modify name, schedule, resources, and other mutable fields. All API error codes and the error envelope convention.