---
title: Environments API
description: Create and manage environments to track monitor status across different deployment stages via the Cronitor API.
---

The Environments API allows you to programmatically create and manage environments. Environments enable you to track monitor status separately across different deployment stages (production, staging, development) without creating duplicate monitors. {% .lead %}

## Authentication

The Environments API requires API key authentication with monitor scopes:
- **`monitor:read`** - Required to list and retrieve environments
- **`monitor:write`** - Required to create, update, and delete environments

Create an API key with the appropriate scopes from the [API Settings](/app/settings/api) page. For more information about API authentication and scopes, see the [API documentation](/docs/api).

---

## Quick Start

### Create an Environment
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Staging",
        "key": "staging",
        "with_alerts": false
    }' \
    https://cronitor.io/api/environments
```

### List All Environments
```bash
curl https://cronitor.io/api/environments -u API_KEY:
```

### Send Telemetry to a Specific Environment
```bash
curl "https://cronitor.link/p/API_KEY/my-job?env=staging&state=complete"
```

---

## Environments

### List Environments

Retrieve all environments for your organization.

#### Endpoint
```bash
GET https://cronitor.io/api/environments
```

#### Query Parameters
- **`page`** (integer) - Page number for pagination (default: 1)

#### Example
```bash
curl https://cronitor.io/api/environments -u API_KEY:
```

#### Response
```json
{
  "page": 1,
  "page_size": 50,
  "count": 3,
  "environments": [
    {
      "key": "production",
      "name": "Production",
      "with_alerts": true,
      "created": "2023-01-01T00:00:00Z",
      "active_monitors": 45,
      "monitor_details": [],
      "status": "healthy",
      "default": true
    },
    {
      "key": "staging",
      "name": "Staging",
      "with_alerts": false,
      "created": "2023-03-15T10:00:00Z",
      "active_monitors": 38,
      "monitor_details": [],
      "status": "healthy",
      "default": false
    },
    {
      "key": "development",
      "name": "Development",
      "with_alerts": false,
      "created": "2023-03-15T10:30:00Z",
      "active_monitors": 12,
      "monitor_details": [],
      "status": "healthy",
      "default": false
    }
  ]
}
```

---

### Create an Environment

Create a new environment to track monitor status separately.

#### Endpoint
```bash
POST https://cronitor.io/api/environments
```

#### Request Body
```json
{
  "name": "QA Environment",
  "key": "qa",
  "with_alerts": false
}
```

#### Parameters
- **`name`** (string, required) - Display name for the environment
- **`key`** (string, required) - Unique identifier used in telemetry events
- **`with_alerts`** (boolean, optional) - Whether to send alerts for this environment (default: false)

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Pre-Production",
        "key": "preprod",
        "with_alerts": true
    }' \
    https://cronitor.io/api/environments
```

#### Response
```json
{
  "key": "preprod",
  "name": "Pre-Production",
  "with_alerts": true,
  "created": "2023-12-01T10:00:00Z",
  "active_monitors": 0,
  "monitor_details": [],
  "status": "healthy",
  "default": false
}
```

---

### Get an Environment

Retrieve details for a specific environment.

#### Endpoint
```bash
GET https://cronitor.io/api/environments/:key
```

#### Example
```bash
curl https://cronitor.io/api/environments/staging -u API_KEY:
```

#### Response
```json
{
  "key": "staging",
  "name": "Staging",
  "with_alerts": false,
  "created": "2023-03-15T10:00:00Z",
  "active_monitors": 38,
  "monitor_details": [
    {"key": "api-health", "name": "API Health Check"},
    {"key": "db-backup", "name": "Database Backup"}
  ],
  "status": "healthy",
  "default": false
}
```

---

### Update an Environment

Update an environment's name or alert settings.

#### Endpoint
```bash
PUT https://cronitor.io/api/environments/:key
```

#### Request Body
```json
{
  "key": "staging",
  "name": "Staging Environment",
  "with_alerts": true
}
```

#### Parameters
- **`key`** (string, required) - The environment key (must match the key in the URL)
- **`name`** (string) - Updated display name
- **`with_alerts`** (boolean) - Whether to send alerts for this environment

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "key": "staging",
        "name": "Staging (Alerts Enabled)",
        "with_alerts": true
    }' \
    https://cronitor.io/api/environments/staging
```

#### Response
Returns the updated environment object.

---

### Delete an Environment

Delete an environment. The default environment cannot be deleted.

#### Endpoint
```bash
DELETE https://cronitor.io/api/environments/:key
```

#### Example
```bash
curl --request DELETE https://cronitor.io/api/environments/old-env -u API_KEY:
```

#### Response
Returns HTTP 204 No Content on success.

**Note:** The default environment cannot be deleted and will return HTTP 400 Bad Request.

---

## Environment Attributes

{% attribute name="key" context="[string] **required**" /%}
Unique identifier for the environment. Used in telemetry events via the `env` parameter and in API queries.

{% attribute name="name" context="[string] **required**" /%}
Display name for the environment. Shown in the Cronitor dashboard.

{% attribute name="with_alerts" context="[boolean] default: false" /%}
Whether to send alerts for monitors in this environment. Set to `false` for non-production environments to avoid alert noise.

{% attribute name="default" context="[boolean] read-only" /%}
Whether this is the default environment. Telemetry events without an `env` parameter are attributed to the default environment.

{% attribute name="active_monitors" context="[integer] read-only" /%}
Count of monitors that have received telemetry in this environment.

{% attribute name="monitor_details" context="[array of objects] read-only" /%}
Array of monitor objects (key and name) active in this environment.

{% attribute name="status" context="[string] read-only" /%}
Overall health status of monitors in this environment.

{% attribute name="created" context="[timestamp] read-only" /%}
ISO 8601 formatted timestamp of when the environment was created.

---

## Using Environments

### Sending Telemetry to an Environment

Include the `env` parameter when sending telemetry events:

```bash
# Using the ping URL
curl "https://cronitor.link/p/API_KEY/my-job?env=staging&state=complete"

# Using the Telemetry API
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "monitor": "my-job",
        "env": "staging",
        "state": "complete"
    }' \
    https://cronitor.io/api/telemetry
```

### Querying by Environment

Most API endpoints support filtering by environment using the `env` query parameter:

```bash
# List monitors for a specific environment
curl "https://cronitor.io/api/monitors?env=staging" -u API_KEY:

# Get metrics for a specific environment
curl "https://cronitor.io/api/metrics?env=production&monitors=api-health" -u API_KEY:

# Get issues for a specific environment
curl "https://cronitor.io/api/issues?env=production" -u API_KEY:
```

---

## Best Practices

- **Enable alerts only for production**: Use `with_alerts: false` for staging and development environments
- **Use consistent naming**: Establish a naming convention (e.g., `production`, `staging`, `development`)
- **Configure CI/CD pipelines**: Pass the appropriate environment when running monitors in different stages
- **Monitor all environments**: Even without alerts, tracking non-production environments helps catch issues early
- **Use environment-specific notification lists**: Create notification lists filtered to specific environments for targeted alerting