How to Manage Uptime Monitoring with a REST API

Clicking around a dashboard is fine when you have five monitors. It stops being fine when you have fifty, or when you need to spin up monitoring for a new service every time your team deploys. At that point, you want an API -- something you can call from a deploy script, a CI pipeline, or a custom dashboard that pulls uptime stats alongside everything else your team cares about.

CronAlert exposes a REST API that lets you do everything the web interface does: create and update monitors, pull check history with uptime percentages, list active incidents, and manage status pages. This post walks through authentication, the available endpoints, and practical examples you can copy into your own scripts.

Authentication

Every API request requires a Bearer token in the Authorization header. You generate API keys in the CronAlert dashboard under Settings > API Keys.

Keys follow a ca_ prefix format -- something like ca_7Bx9kW2mPqR4vT8nY1dL... (32 characters after the prefix). When you create a key, CronAlert shows the full value exactly once. After that, only a SHA-256 hash is stored on our side, so there is no way to retrieve it later. Copy it somewhere safe.

To authenticate, include the key as a Bearer token:

Authorization: Bearer ca_your_api_key_here

If the key is missing or invalid, the API returns a 401 Unauthorized response. If your plan does not permit the operation you are attempting, you get a 403 Forbidden with a message explaining what is required.

Quick start

Here is the simplest possible API call -- listing all your monitors:

curl -s https://cronalert.com/api/v1/monitors \
  -H "Authorization: Bearer ca_your_api_key_here" | python3 -m json.tool

That returns a JSON object with your monitors, their current status, and pagination metadata. If this works, you are authenticated and ready to go.

Endpoints reference

The base URL for all endpoints is https://cronalert.com/api/v1. Here is the full list:

All list endpoints support page and limit query parameters for pagination. The monitors list also accepts a status filter (up, down, or unknown). The checks endpoint accepts a since parameter with an ISO 8601 date to narrow the time range.

Practical examples

Below are curl examples for the most common operations. Replace ca_your_api_key_here with your actual key and adjust IDs and URLs for your setup.

Create a monitor

This creates a monitor that checks an API health endpoint using a GET request and expects a 200 response:

curl -X POST https://cronalert.com/api/v1/monitors \
  -H "Authorization: Bearer ca_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Health",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatusCode": 200
  }'

The response includes the created monitor object with its assigned id, which you will need for subsequent operations. The check interval is determined by your plan -- 3 minutes on Free, 1 minute on Pro and above. You do not set it manually.

Get uptime stats for a monitor

Pull the last 7 days of check results for a specific monitor, including the calculated uptime percentage and average response time:

curl -s "https://cronalert.com/api/v1/monitors/MONITOR_ID/checks?limit=50&since=2026-03-03T00:00:00Z" \
  -H "Authorization: Bearer ca_your_api_key_here"

The response includes an array of individual check results along with summary fields for uptimePercentage and avgResponseTime. This is what you would use to feed data into a Grafana panel, a Datadog dashboard, or a custom internal status board.

List active incidents

To see which monitors are currently experiencing issues across your entire account:

curl -s https://cronalert.com/api/v1/incidents?page=1&limit=50 \
  -H "Authorization: Bearer ca_your_api_key_here"

Each incident includes the monitor it belongs to, when the incident started, its current status, and any updates that have been posted. You can also scope incidents to a single monitor using /monitors/:id/incidents if you only care about a specific service.

Delete a monitor

When you decommission a service, clean up the monitor to keep your dashboard tidy:

curl -X DELETE https://cronalert.com/api/v1/monitors/MONITOR_ID \
  -H "Authorization: Bearer ca_your_api_key_here"

This deletes the monitor and all associated check history. The operation is irreversible, so be sure you have the right ID before running this in a script.

CI/CD integration ideas

The real power of a monitoring API shows up when you wire it into your deployment pipeline. Here are two patterns that work well.

Auto-create monitors on deploy

Add a step at the end of your deploy script that registers a monitor for the deployed service. If you are deploying a new microservice to production, the deploy script can POST to the monitors endpoint so there is never a gap between "service is live" and "service is monitored." Here is a simplified example:

#!/bin/bash
# deploy.sh -- deploy service and register monitor

SERVICE_NAME="checkout-api"
SERVICE_URL="https://checkout.example.com/health"
CRONALERT_KEY="ca_your_api_key_here"

# ... your deploy steps here ...

# Register monitor after successful deploy
curl -X POST https://cronalert.com/api/v1/monitors \
  -H "Authorization: Bearer $CRONALERT_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"$SERVICE_NAME\",
    \"url\": \"$SERVICE_URL\",
    \"method\": \"GET\",
    \"expectedStatusCode\": 200
  }"

echo "Monitor registered for $SERVICE_NAME"

If the monitor already exists, you can adjust the script to check for it first with a GET request and skip creation, or use a PUT to update the URL if it has changed.

Post-deploy verification

After a deploy completes, poll the checks endpoint to confirm the service is actually responding. This catches cases where the deploy succeeded but the service is crashing on startup or returning errors:

# Wait for CronAlert to run a check, then verify the result
sleep 180  # wait for at least one check cycle

RESPONSE=$(curl -s "https://cronalert.com/api/v1/monitors/MONITOR_ID/checks?limit=1" \
  -H "Authorization: Bearer $CRONALERT_KEY")

STATUS=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['data'][0]['statusCode'])")

if [ "$STATUS" != "200" ]; then
  echo "Post-deploy check failed with status $STATUS -- rolling back"
  # trigger rollback
  exit 1
fi

echo "Post-deploy check passed"

This is a simple pattern, but it turns your monitoring system into an automated quality gate. If the health check fails after deploy, you can trigger a rollback before customers notice.

Plan access and write permissions

API access is available on every plan, but the scope differs:

• Free plan -- read-only access. You can use all GET endpoints to retrieve monitors, check history, incidents, and status pages. Any attempt to use POST, PUT, or DELETE returns a 403 response with a message indicating that write access requires a Pro plan or higher.
• Pro, Team, and Business plans -- full read-write access. All endpoints and methods are available. This is the level you need for CI/CD integration, automated monitor creation, or anything that modifies your monitoring setup programmatically.

You can manage your API keys at Settings > API Keys. Create multiple keys for different purposes -- one for CI/CD, one for your dashboard integration, one for a team member's script -- and revoke them individually if one is compromised.

Frequently asked questions

Is the API available on the free plan?

Yes, with read-only access. Free plan users can call any GET endpoint to retrieve monitor data, check results, incidents, and status pages. Write operations -- creating, updating, or deleting monitors -- require a Pro plan or higher. The API returns a 403 status code if you attempt a write operation on the free plan.

How are API keys authenticated?

API keys are passed as Bearer tokens in the Authorization header. Each key starts with the ca_ prefix followed by a 32-character nanoid. CronAlert stores only a SHA-256 hash of the key server-side, which means the full key is displayed only once when you create it. If you lose it, you need to generate a new one.

Can I create monitors automatically during deployments?

Yes. The POST /api/v1/monitors endpoint is designed exactly for this. Pass the monitor name, URL, HTTP method, and expected status code in the request body. Many teams add this as a post-deploy step in their CI/CD pipeline so every new service gets monitored the moment it goes live. See the CI/CD integration section above for a working example.

What happens if I hit a rate limit?

The API returns a 429 Too Many Requests status code with a Retry-After header that tells you how many seconds to wait before retrying. The limits are generous enough for normal automation workflows, but if you are polling aggressively from multiple scripts, you may want to add backoff logic or consolidate your requests.

Start building

The API turns CronAlert from a tool you check into a tool that works for you. Automate monitor creation in your deploy pipeline, pull uptime metrics into your existing dashboards, or build custom alerting logic on top of the incident data. Everything the dashboard can do, the API can do from a script.

If you do not have an account yet, sign up for free -- 25 monitors with 3-minute checks, read-only API access, and alerts via Slack, Discord, email, and webhooks. When you are ready for full API access, Pro starts at $4/month.