# Promote a release

Source: https://www.jawsdeploy.net/rest-api/releases-promote | Section: Releases

Promote the latest (or a specific) version of a project to one or more environments.

`POST /api/release/promote`

Promotes a project's release without needing to know its release ID. If `version` is omitted, the highest existing version is used - highest by SemVer across the whole project, which is not necessarily the most recently created release and does not take channels into account. The deployment payload is the same as `/api/release/deploy` aside from looking up the release by project and version.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | ID of the project to promote. |
| `version` | body | string | no | Specific version to promote, matched **exactly** as the release was created. Unlike [Get a release](https://www.jawsdeploy.net/rest-api/releases-details) and [List deployments](https://www.jawsdeploy.net/rest-api/deployments-list), this does *not* fall back to a SemVer equivalent - `6.1` will not find a release stored as `6.1.0`. That is deliberate: those two are reads, and this one starts a deployment, so a version it was not given exactly is refused rather than interpreted. Defaults to the highest existing version when omitted. |
| `environmentName` | body | string | no | Single environment to deploy to. |
| `phaseName` | body | string | no | Promote to every environment in the given lifecycle phase. |
| `environments` | body | array<object> | no | Per-environment machine rules - same shape as `/api/release/deploy`. |
| `redownloadPackages` | body | boolean | no | Force agents to redownload packages. |
| `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 `projectId`, no release found to promote, 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](https://www.jawsdeploy.net/rest-api/environments-update), or when the release has not reached its lifecycle phase yet. Check `enabled` on [List environments](https://www.jawsdeploy.net/rest-api/environments-list) to tell the two apart. |
| 409 | Resource usage limit exceeded. |
| 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. |

Example request:

```
POST /api/release/promote HTTP/1.1
Authorization: Basic <base64(serviceAccountId:apiKey)>
Content-Type: application/json

{
  "projectId": "prj_abc123",
  "environmentName": "Production"
}
```

Example response:

```
{
  "deploymentId": "dep_d4e5f6",
  "deploymentIds": ["dep_d4e5f6"]
}
```