---
title: Cronitor API Docs
description: Documentation on how to use Cronitor's API.
---
The Cronitor API exposes the functionality and data available on the Cronitor dashboard, as well as bulk operations and other API-only features. {% .lead %}

The same resources are available to coding agents through the [Cronitor MCP server](/docs/mcp-server) and to the shell through [CronitorCLI](/docs/using-cronitor-cli).

## Authentication

The Cronitor API uses API Keys to authenticate requests. Keys can be viewed & managed from the [API Settings](/app/settings/api) page.

Every account starts with two API keys with different permission levels:

| Key | Permissions | Use Case |
|-----|-------------|----------|
| **Telemetry** | `monitor:telemetry` | Send telemetry data (pings, metrics) |
| **SDK Integration** | All resource scopes | Full access to monitors, sites, status pages, issues, notification integrations, etc. |

### API Authentication
Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key as the basic auth username value. You do not need to provide a password.
```bash
curl https://cronitor.io/api/monitors -u API_KEY:
# The colon prevents curl from asking for a password.
```

_All REST API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail._

#### Telemetry API Authentication
The [Telemetry API](/docs/telemetry-api) is hosted on a separate domain, `cronitor.link`, and uses an API key embedded in the URL to authenticate requests.

```bash
curl https://cronitor.link/p/:apiKey/:monitorKey
```
_Telemetry API requests can be made over HTTPS or HTTP. All requests, including those with invalid credentials, will return a 200 response. Authentication is performed downstream of event ingestion._

### API Key Scopes

To create custom API Keys: Visit the [API Settings](/app/settings/api) page, click "Create API Key", select the required scopes for your use case, and name your key for easy identification.

To access different Cronitor resources, create API Keys with the appropriate scopes:

| Scope | Description |
|-------|-------------|
| `monitor:read` | List and retrieve monitor details |
| `monitor:write` | Create, update, and delete monitors |
| `monitor:telemetry` | Send monitoring data (pings, metrics) |
| `issue:read` | List and retrieve issues _(also used for maintenance windows)_ |
| `issue:write` | Create, update, and delete issues _(also used for maintenance windows)_ |
| `statuspage:read` | List and retrieve status pages |
| `statuspage:write` | Create, update, and delete status pages |
| `site:read` | List and retrieve site monitoring data |
| `site:write` | Create, update, and delete site monitors |
| `integration:read` | List and retrieve notification integrations |
| `integration:write` | Create and delete notification integrations |

## API Endpoints

Cronitor provides several specialized APIs for different purposes:

### Core APIs
- [**Monitors API**](/docs/monitors-api): Create, update, and manage monitors
- [**Telemetry API**](/docs/telemetry-api): Send monitoring data from your systems
- [**Metrics API**](/docs/metrics-api): Retrieve performance and reliability metrics

### Organization & Configuration
- [**Groups API**](/docs/groups-api): Organize monitors into groups for bulk operations
- [**Notifications API**](/docs/notifications-api): Configure where and how alerts are sent
- [**Integrations API**](/docs/integrations-api): List, create, and delete alert destinations
- [**Environments API**](/docs/environments-api): Manage deployment environments
- [**API Keys**](/docs/api-keys): Create and manage API keys with custom scopes

### Incidents & Status
- [**Issue API**](/docs/issues-api): Manage incidents and maintenance events
- [**Maintenance API**](/docs/maintenance-windows-api): Schedule and manage maintenance windows
- [**StatusPage API**](/docs/statuspages-api): Control your status pages

### Real User Monitoring
- [**Sites API**](/docs/sites-api): Manage RUM sites for web performance monitoring

## Versioning

When backwards-incompatible changes are made to the Cronitor API, a new, dated version is released. The current version is `2025-11-28`.

_Requests without a version header default to `2020-10-01`, the first dated release._

To set the API version on a specific request, send a Cronitor-Version header.
```bash
curl https://cronitor.io/api/monitors \
  -u API_KEY: \
  -H "Cronitor-Version: 2025-11-28"
```

## Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

- `2xx`: Success
- `4xx`: Client error (invalid request, authentication issues)
- `5xx`: Server error

Error responses include a JSON body with details about what went wrong:

```json
{
  "error": {
    "message": "Description of the error",
    "type": "error_type"
  }
}
```

## Rate Limits

The API has rate limits to ensure fair usage. If you exceed these limits, you'll receive a `429 Too Many Requests` response. The response headers include information about your current rate limit status.

## Browser-based API

You can visit any API resource in a browser to view the JSON representation of that resource, and test making API requests using a simple GUI. Try it out — [https://cronitor.io/api/monitors](https://cronitor.io/api/monitors)

_Tip: Any URL within the Cronitor app, e.g. `https://cronitor.io/app/issues`, can have the `/app/` swapped for `/api/` to view the underlying API response._{% .small %}

## Changelog
Previous versions of the Cronitor API used numerically versioned resources (e.g. /v3/) when making breaking changes. The documentation for those versions can be found here:
- **2026-09-04**: New `integration:read` and `integration:write` scopes for the [Integrations API](/docs/integrations-api). SDK Integration keys hold every resource scope, so every existing SDK key gained both scopes automatically; custom keys must be updated to add them. Integration public identity is the **label**, scoped by service. `GET`/`DELETE /api/integrations` use `?service=` and `?label=`. Notification lists and monitors return labels; writes accept a label or a key-based identifier slug. A duplicate `name` for the same service is a `400` validation error (`{"name": ["name must be unique"]}`). Existing duplicate labels were renamed by a one-time migration: later Slack rows became `#channel (workspace)`, later PagerDuty rows `Service (account)`, and other services `Name 2`, `Name 3`. New Slack and PagerDuty connections whose name is already taken receive the same qualified label instead of an error. Autoincrement `service:pk` ids are not returned. Slack webhook URLs and PagerDuty keys are never returned.
- **2025-11-28**: _current_ — `schedule` replaced by `schedules` array, badge URLs consolidated into `badges` object
- **2020-10-01**: First dated version release (default for requests without a version header)

Documentation for the numbered v1, v2, and v3 resources is no longer published. If you still call one, [contact support](mailto:support@cronitor.io) for help moving to the current dated version.