Cronitor API Docs

The Cronitor API exposes the functionality and data available on the Cronitor dashboard, as well as bulk operations and other API-only features.

Authentication

The Cronitor API uses API Keys to authenticate requests. Keys can be viewed & managed from the API Settings page.

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

Key	Permissions	Use Case
Telemetry	`monitor:telemetry`	Send monitoring data (pings, metrics)
SDK Integration	`monitor:read`, `monitor:write`, `monitor:telemetry`	Full monitor management and data collection

API Authentication

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

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. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Telemetry API Authentication

The Telemetry API is hosted on a separate domain, cronitor.link, and uses an API key embedded in the URL to authenticate requests.

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

API Endpoints

Cronitor provides several specialized APIs for different purposes:

Monitor API: Create, update, and manage monitors
Telemetry API: Send monitoring data from your systems
Metrics API: Retrieve performance and reliability metrics
Issue API: Manage incidents and maintenance events
Maintenance API: Schedule and manage maintenance windows
StatusPage API: Control your status pages

Versioning

When backwards-incompatible changes are made to the Cronitor API, a new, dated version is released. The current version is 2020-10-01.

*All requests will use the current version unless you override it.

To set the API version on a specific request, send a Cronitor-Version header.

curl https://cronitor.io/api/monitors \
  -u API_KEY: \
  -H "Cronitor-Version: 2020-10-01"

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:

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

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.

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:

2020-10-01: current
API v3
API v2
API v1