API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings → API Keys.

Request header

Authorization: Bearer your_api_key_here

Example · curl

curl -s https://api.alerto.io/api/v1/monitors \
  -H "Authorization: Bearer ak_live_abc123..."

Keep your keys safe. API keys have full access to your account. Don't commit them to version control. Use environment variables instead.

Monitors

GET /api/v1/monitors

List all monitors in your account. Returns an array of monitor objects.

Example

curl -s https://api.alerto.io/api/v1/monitors \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "monitors": [
    {
      "id": 42,
      "name": "api.myapp.com",
      "type": "https",
      "target": "https://api.myapp.com/health",
      "interval": 60,
      "status": "up",
      "last_check": "2026-04-21T08:00:12Z",
      "uptime_7d": 99.98,
      "avg_response_ms": 126
    }
  ]
}

POST /api/v1/monitors

Create a new monitor.

Parameter	Type	Description
`name` required	string	Display name for the monitor
`type` required	string	`http`, `https`, `tcp`, `dns`, `ping`, `visual`, `blacklist`
`target` required	string	URL, hostname, or IP to monitor
`interval` optional	integer	Check interval in seconds (default: 60)
`timeout` optional	integer	Timeout in seconds (default: 30)
`keyword` optional	string	Expected keyword in response body (HTTP only)
`port` optional	integer	Port number (TCP/DNS monitors)
`regions` optional	array	Probe regions: `["us", "eu", "il"]`
`integrations` optional	array	Array of integration IDs to link

Example

curl -s -X POST https://api.alerto.io/api/v1/monitors \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "https",
    "target": "https://api.myapp.com/health",
    "interval": 30,
    "keyword": "ok",
    "regions": ["us", "eu"],
    "integrations": [1, 3]
  }'

GET /api/v1/monitors/:id

Get detailed information about a specific monitor, including current status, configuration, and latest check result.

PUT /api/v1/monitors/:id

Update a monitor's configuration. Accepts the same parameters as create. Only provided fields are updated.

DELETE /api/v1/monitors/:id

Delete a monitor and all its associated history. This action is irreversible.

POST /api/v1/monitors/:id/check

Trigger an immediate check for this monitor. Returns the check result. Rate limited to 1 request per monitor per 10 seconds.

Example

curl -s -X POST https://api.alerto.io/api/v1/monitors/42/check \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "status": "up",
  "response_time_ms": 142,
  "status_code": 200,
  "region": "eu",
  "checked_at": "2026-04-21T08:12:33Z"
}

GET /api/v1/monitors/:id/history

Get check history for a monitor. Returns paginated results.

Parameter	Type	Description
`from` optional	string	ISO 8601 start date
`to` optional	string	ISO 8601 end date
`limit` optional	integer	Results per page (default: 100, max: 1000)
`offset` optional	integer	Pagination offset

Example

curl -s "https://api.alerto.io/api/v1/monitors/42/history?from=2026-04-14T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $API_KEY"

GET /api/v1/monitors/:id/uptime

Get uptime percentage for a monitor over a specified period.

Parameter	Type	Description
`period` optional	string	`24h`, `7d`, `30d`, `90d` (default: `30d`)

Response · 200

{
  "monitor_id": 42,
  "period": "30d",
  "uptime_percentage": 99.97,
  "total_checks": 43200,
  "failed_checks": 13,
  "avg_response_ms": 134
}

Incidents

GET /api/v1/incidents

List incidents across all monitors. Includes downtime start/end, affected monitor, and resolution details.

Parameter	Type	Description
`monitor_id` optional	integer	Filter by monitor
`status` optional	string	`open` or `resolved`
`limit` optional	integer	Results per page (default: 50)

Example

curl -s "https://api.alerto.io/api/v1/incidents?status=open" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "incidents": [
    {
      "id": 87,
      "monitor_id": 42,
      "monitor_name": "api.myapp.com",
      "status": "open",
      "started_at": "2026-04-21T07:45:00Z",
      "resolved_at": null,
      "duration_seconds": null,
      "cause": "HTTP 503 from us, eu probes"
    }
  ]
}

Status Pages

GET /api/v1/status-pages

List all status pages in your account.

POST /api/v1/status-pages

Create a new public status page.

Parameter	Type	Description
`name` required	string	Status page title
`slug` required	string	URL slug (e.g. `my-app`)
`monitors` required	array	Array of monitor IDs to display
`custom_domain` optional	string	Custom domain (e.g. `status.myapp.com`)
`description` optional	string	Page description shown to visitors

Example

curl -s -X POST https://api.alerto.io/api/v1/status-pages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyApp Status",
    "slug": "myapp",
    "monitors": [42, 43, 44],
    "custom_domain": "status.myapp.com"
  }'

PUT /api/v1/status-pages/:id

Update an existing status page. Accepts the same parameters as create.

Integrations

GET /api/v1/integrations

List all configured integrations (Telegram, Email, Slack, Webhooks, SMS).

POST /api/v1/integrations

Create a new integration.

Parameter	Type	Description
`type` required	string	`telegram`, `email`, `slack`, `webhook`, `sms`
`name` required	string	Display name
`config` required	object	Type-specific configuration (see below)

Example · Telegram integration

curl -s -X POST https://api.alerto.io/api/v1/integrations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "name": "Ops channel",
    "config": {
      "chat_id": "-1001234567890"
    }
  }'

Example · Webhook integration

curl -s -X POST https://api.alerto.io/api/v1/integrations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "PagerDuty",
    "config": {
      "url": "https://events.pagerduty.com/integration/abc/enqueue",
      "method": "POST",
      "headers": {"X-Custom": "value"}
    }
  }'

GET /api/v1/monitors/:id/integrations

Get integrations linked to a specific monitor.

PUT /api/v1/monitors/:id/integrations

Link integrations to a monitor. Replaces existing links.

Example

curl -s -X PUT https://api.alerto.io/api/v1/monitors/42/integrations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration_ids": [1, 3, 7]}'

Blacklist / DNSBL

POST /api/v1/blacklist/check

Run a manual IP blacklist check against all supported DNSBL servers. Returns results from each server.

Parameter	Type	Description
`ip` required	string	IPv4 address to check

Example

curl -s -X POST https://api.alerto.io/api/v1/blacklist/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "1.2.3.4"}'

Response · 200

{
  "ip": "1.2.3.4",
  "listed": false,
  "checked_servers": 19,
  "results": [
    { "server": "zen.spamhaus.org", "listed": false },
    { "server": "bl.spamcop.net", "listed": false }
    // ... 17 more servers
  ]
}

GET /api/v1/blacklist/servers

List all DNSBL servers used for blacklist checks.

Load Tests

POST /api/v1/load-tests

Start a new load test against your own target. Only test infrastructure you own.

Parameter	Type	Description
`url` required	string	Target URL to load test
`duration` optional	integer	Duration in seconds (default: 30, max: 300)
`concurrency` optional	integer	Concurrent connections (default: 10, max: 100)
`method` optional	string	HTTP method (default: GET)

Example

curl -s -X POST https://api.alerto.io/api/v1/load-tests \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.myapp.com/health",
    "duration": 60,
    "concurrency": 25
  }'

GET /api/v1/load-tests

List all load tests. Returns test metadata, status, and summary results.

GET /api/v1/load-tests/:id

Get detailed results for a completed load test, including percentile latencies, error rates, and throughput.

Response · 200

{
  "id": 15,
  "status": "completed",
  "url": "https://api.myapp.com/health",
  "duration": 60,
  "concurrency": 25,
  "total_requests": 14832,
  "successful": 14819,
  "failed": 13,
  "rps": 247.2,
  "latency": {
    "avg_ms": 101,
    "p50_ms": 89,
    "p95_ms": 198,
    "p99_ms": 342,
    "max_ms": 1204
  }
}

GET /api/v1/load-tests/:id/stream

Real-time SSE (Server-Sent Events) stream of load test progress. Connect while the test is running to receive live metrics.

Example · SSE stream

curl -s -N https://api.alerto.io/api/v1/load-tests/15/stream \
  -H "Authorization: Bearer $API_KEY"

# Stream output:
data: {"elapsed_s":5,"rps":241,"avg_ms":98,"errors":0}
data: {"elapsed_s":10,"rps":253,"avg_ms":102,"errors":1}
// ...

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with details:

Error response

{
  "error": "monitor_not_found",
  "message": "Monitor with ID 999 does not exist",
  "status": 404
}

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request — check your parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not found
`429`	Rate limited — slow down
`500`	Internal server error

Rate Limits

API requests are rate limited per API key:

General endpoints: 60 requests per minute
Trigger check: 1 per monitor per 10 seconds
Load tests: 1 concurrent test per account

Rate limit headers are included in every response:

Rate limit headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1713686400

When rate limited, you'll receive a 429 response. Wait until the reset timestamp before retrying.

Endpoints

Authentication

Monitors

Incidents

Status Pages

Integrations

Blacklist / DNSBL

Load Tests

Errors

Rate Limits