# Deploy a release

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

Run an existing release against one or more environments.

`POST /api/release/deploy`

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](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 - 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. |

Example request:

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

{
  "releaseId": "rel_9f4c...",
  "environmentName": "Staging"
}
```

Example response:

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