Description
Deploys an existing release. You can target an environment by name, a lifecycle phase, or pass a structured environments list with per-environment machine rules.
Returns the new deployment IDs (one per environment). The deployment runs asynchronously - poll GET /api/deployment for status.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
releaseId |
body | string | yes | ID of the release to deploy. |
environmentName |
body | string | no | Single environment to deploy to (alternative to environments). |
phaseName |
body | string | no | Deploy to every environment in the given lifecycle phase. |
environments |
body | array<object> | no | List of { environmentName, machineMode, machineIds? } setups for fine-grained control. |
redownloadPackages |
body | boolean | no | Force agents to redownload packages even if cached. |
deploymentDateUnixMillis |
body | integer | no | Schedule the deployment for a future time (UTC unix millis). |
excludeStepNames |
body | array<string> | no | Skip these step names from the deployment. |
Errors
| Status | Meaning |
|---|---|
400 |
Invalid releaseId, no matching environments, or validation failure. |
400 |
One or more of the named environments is not available for this release - the message reads some environments are not available (disabled or blocked by phase progression for this release) and lists them. An environment is unavailable when it has been switched off with Update an environment, or when the release has not reached its lifecycle phase yet. Check enabled on List environments to tell the two apart. |
409 |
Resource usage limit exceeded - response includes resourceUsageErrors. |
401 |
Missing or invalid Basic auth credentials, the service account may not deploy this project, or it may not deploy to one of the environments named - the last of those lists the environment IDs it refused. |