Cronitor API

Environments 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.

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 page. For more information about API authentication and scopes, see the API documentation.

Quick Start

Create an Environment

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

curl https://cronitor.io/api/environments -u API_KEY:

Send Telemetry to a Specific Environment

curl "https://cronitor.link/p/API_KEY/my-job?env=staging&state=complete"

Environments

List Environments

Retrieve all environments for your organization.

Endpoint

GET https://cronitor.io/api/environments

Query Parameters

  • page (integer) - Page number for pagination (default: 1)

Example

curl https://cronitor.io/api/environments -u API_KEY:

Response

{
  "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

POST https://cronitor.io/api/environments

Request Body

{
  "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

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

{
  "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

GET https://cronitor.io/api/environments/:key

Example

curl https://cronitor.io/api/environments/staging -u API_KEY:

Response

{
  "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

PUT https://cronitor.io/api/environments/:key

Request Body

{
  "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

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

DELETE https://cronitor.io/api/environments/:key

Example

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

key[string] **required**

Unique identifier for the environment. Used in telemetry events via the env parameter and in API queries.

name[string] **required**

Display name for the environment. Shown in the Cronitor dashboard.

with_alerts[boolean] default: false

Whether to send alerts for monitors in this environment. Set to false for non-production environments to avoid alert noise.

default[boolean] read-only

Whether this is the default environment. Telemetry events without an env parameter are attributed to the default environment.

active_monitors[integer] read-only

Count of monitors that have received telemetry in this environment.

monitor_details[array of objects] read-only

Array of monitor objects (key and name) active in this environment.

status[string] read-only

Overall health status of monitors in this environment.

created[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:

# 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:

# 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
Previous
Notifications
Next
Issues