# Create an environment

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

Create a new deployment environment in a workspace.

`POST /api/environment`

Creates an environment. Environments group machines and cloud targets that receive deployments together.

A new environment is live as soon as it exists. Pass `enabled` as `false` to create one that cannot yet receive deployments - useful when the machines are not assigned yet - and turn it on later with [Update an environment](https://www.jawsdeploy.net/rest-api/environments-update).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | body | string | yes | ID of the workspace. |
| `name` | body | string | yes | Environment name (must be unique within the workspace). |
| `sortOrder` | body | integer | no | Display order in the UI. |
| `color` | body | string | no | Hex color used for the environment chip. |
| `enabled` | body | boolean | no | Whether the environment can receive deployments. Defaults to `true`, so an environment created without this field is live immediately. Pass `false` to stage one before opening it up. See [Update an environment](https://www.jawsdeploy.net/rest-api/environments-update) for what the flag does. |

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid `workspaceId` or validation failure (e.g. duplicate name). |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks the required role. |

Example request:

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

{
  "workspaceId": "ws_abc",
  "name": "Staging",
  "sortOrder": 20,
  "color": "#ffb454",
  "enabled": true
}
```

Example response:

```
{ "environmentId": "env_b" }
```