# Environments API

> List, create, rename and delete environments, and choose the account's default environment, with the ApiTraffic REST API.

Source: https://www.apitraffic.io/docs/api-reference/environments

An environment separates the traffic of one stage of your application, such as production and staging. Every API token belongs to one environment, and traffic an SDK sends with that token is recorded there. See [Environments](https://www.apitraffic.io/docs/account/environments) for managing them in the app.

**Permissions:** any member, or a `user` or `administrator` API token, can list, create and update environments. Deleting one needs an owner or admin, or an `administrator` API token. **Limit:** the number of environments depends on the plan.

## The environment object

- **sid (string, required)**:
  The environment's identifier (6 lowercase letters and digits).

- **accountSid (string, required)**:
  The account.

- **name (string, required)**:
  The environment's name.

- **isDefault (boolean, required)**:
  Whether this is the account's default environment. Every account has exactly one.

- **createdAt (string, required)**:
  When the environment was created (ISO 8601).

- **updatedAt (string)**:
  When it was last changed.

## List environments

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/environments`

Returns every environment in the account, sorted by name.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Response

- **hasMore (boolean, required)**:
  Always `false`: every environment is returned in one response.

- **records (object[], required)**:
  The environments, as [environment objects](#the-environment-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/environments`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
const production = records.find((environment) => environment.isDefault);
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "prd7k2",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "name": "Production",
      "isDefault": true,
      "createdAt": "2026-03-02T15:20:11.000Z",
      "updatedAt": "2026-03-02T15:20:11.000Z"
    },
    {
      "sid": "stg4m8",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "name": "Staging",
      "isDefault": false,
      "createdAt": "2026-04-08T09:00:00.000Z",
      "updatedAt": "2026-04-08T09:00:00.000Z"
    }
  ]
}
```

## Get environment

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}`

Returns one environment.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment's identifier.

### Response

An [environment object](#the-environment-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/stg4m8 \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/environments/stg4m8`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const environment = await response.json();
```

```json 200
{
  "sid": "stg4m8",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "name": "Staging",
  "isDefault": false,
  "createdAt": "2026-04-08T09:00:00.000Z",
  "updatedAt": "2026-04-08T09:00:00.000Z"
}
```

## Create environment

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/environments`

Creates an environment. To send traffic to it, [create an API token](https://www.apitraffic.io/docs/api-reference/api-tokens#create-api-token) for it and give that token to your SDK.

**Limit:** past the plan's environment limit, the API answers `409` with code `2213`; `data` carries `allowance` and `currentCount`.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Body parameters

- **name (body, string, required)**:
  The environment's name, for example `Staging`.

- **isDefault (body, boolean, default false)**:
  Make it the account's default environment. The previous default stops being the default.

### Response

The new [environment object](#the-environment-object).

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Staging" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/environments`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Staging' }),
});
const environment = await response.json();
```

```json 200
{
  "sid": "stg4m8",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "name": "Staging",
  "isDefault": false,
  "createdAt": "2026-10-20T11:00:00.000Z",
  "updatedAt": "2026-10-20T11:00:00.000Z"
}
```

## Update environment

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}`

Renames an environment or makes it the default. Send only the fields you want to change.

> **Note:** The default environment cannot be unset directly: sending `isDefault: false` for it answers `409` with code `2109`. Make another environment the default instead.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment's identifier.

### Body parameters

- **name (body, string)**:
  The new name.

- **isDefault (body, boolean)**:
  `true` makes this the default environment.

### Response

The updated [environment object](#the-environment-object).

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/stg4m8 \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Staging (EU)" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/environments/stg4m8`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Staging (EU)' }),
});
const environment = await response.json();
```

```json 200
{
  "sid": "stg4m8",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "name": "Staging (EU)",
  "isDefault": false,
  "createdAt": "2026-04-08T09:00:00.000Z",
  "updatedAt": "2026-10-20T11:05:00.000Z"
}
```

## Delete environment

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}`

Deletes an environment. Every API token and MCP token that belongs to it, and every OAuth connection to it, is revoked at the same time, so SDKs using those tokens stop sending traffic. The default environment cannot be deleted.

> **Warning:** This cannot be undone. Move any SDK that uses the environment's tokens to another environment first.

**Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment's identifier.

### Response

- **sid (string, required)**:
  The deleted environment's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/stg4m8 \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/environments/stg4m8`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "stg4m8",
  "deleted": true
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `403` | `2010` | Deleting an environment without owner, admin or `administrator` access. |
| `404` | `4000` | No environment with that sid in this account. |
| `409` | `2109` | The default environment cannot be deleted or unset. |
| `409` | `2213` | The plan's environment limit is reached. |
| `503` | `2108` | The environment's tokens could not be revoked right now. Nothing was changed; retry. |

## Related

- [Environments](https://www.apitraffic.io/docs/account/environments):
    Manage environments in the app.

- [API tokens API](https://www.apitraffic.io/docs/api-reference/api-tokens):
    Create the token an SDK uses for an environment.