# Update an environment

Source: https://www.jawsdeploy.net/rest-api/environments-update | Section: Environments

Rename an environment, restyle it, reorder it, or take it out of service.

`PUT /api/environment`

Updates an environment in place. Pass only the fields you want to change - `name`, `sortOrder`, `color` and `enabled` are each left alone when you leave them out.

Renaming an environment does not affect releases that already targeted it.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `environmentId` | body | string | yes | ID of the environment. |
| `name` | body | string | no | New name. |
| `sortOrder` | body | integer | no | New display order. |
| `color` | body | string | no | New hex color. |
| `enabled` | body | boolean | no | Set to `false` to stop the environment receiving deployments, or `true` to let it again. **Omit it and the current value is kept.** See below. |

### Disabling an environment

`enabled` is the switch for taking an environment out of service without deleting it. It is the field to reach for during a maintenance window, or to freeze production while an incident is open.

The environment keeps everything else. Its machines stay assigned, its lifecycle phases still name it, its variables keep their scoping, and its deployment history is untouched. Re-enable it and it carries on. That is the difference between this and [Delete an environment](https://www.jawsdeploy.net/rest-api/environments-delete), which is a soft delete the environment does not come back from.

**What a disabled environment refuses:**

- A [deploy](https://www.jawsdeploy.net/rest-api/releases-deploy) or [promote](https://www.jawsdeploy.net/rest-api/releases-promote) naming it fails up front with `400`, and the message lists the environment among those that are not available. The same message covers environments blocked by lifecycle phase progression, so a disabled environment and a not-yet-reachable one read alike - check `enabled` on [List environments](https://www.jawsdeploy.net/rest-api/environments-list) to tell them apart.
- A lifecycle will not promote a release into it automatically.

**What it does not do:** disabling is not a stop button for work already under way. A deployment that was queued before the environment was disabled is not cancelled. It fails when it is picked up, logging `Deployment blocked: the environment is disabled.` and finishing as `Failed`. To stop something already running, use [Cancel a deployment](https://www.jawsdeploy.net/rest-api/deployments-cancel) as well.

Environments are enabled when created unless [Create an environment](https://www.jawsdeploy.net/rest-api/environments-create) is told otherwise, and every environment that existed before this flag was added is enabled. The current value is returned by [List environments](https://www.jawsdeploy.net/rest-api/environments-list).

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid `environmentId` or validation failure. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks the required role. |

Example request:

```
PUT /api/environment HTTP/1.1
Host: app.jawsdeploy.net
Authorization: Basic <base64(serviceAccountId:apiKey)>
Content-Type: application/json

{
  "environmentId": "env_b",
  "enabled": false,
  "color": "#7ee787"
}
```

Example response:

```
{}
```