Monitors API

The Monitors API is part of the User API. It lets you list, create, read, update, and delete monitors programmatically, plus pull check history, performance metrics, and uptime summaries. All endpoints in this family authenticate with a user API token sent as a Bearer token.

Base URL and authentication

https://api.statusradar.dev/v1

Every request (except the public uptime route below) requires a user API token:

Authorization: Bearer YOUR_API_TOKEN

Generate a token at Dashboard → Settings → API (/dashboard/settings/api). The token is shown only once; if you lose it, generate a new one. Requests are scoped to the team that owns the token — you can only see and manage monitors that belong to your active team. See API Authentication.

Create, update, and delete operations also require the manage_monitors permission. Team roles owner, admin, and member have it; viewer is read-only. See Teams.

Response format

All responses use a consistent JSON envelope.

Success:

{
  "success": true,
  "message": "Success",
  "data": { ... }
}

Error:

{
  "success": false,
  "message": "Monitor not found",
  "errors": []
}

Status codes: 200 OK, 201 created, 400 invalid JSON body, 401 unauthorized, 403 forbidden (missing permission), 404 monitor not found, 422 validation failed, 500 server error.

Endpoints

Monitor types and fields

A monitor has a type plus a set of common fields and, depending on the type, a few type-specific fields.

Common fields

Monitor type. Type server (agent-based host metrics) is not created through this API — install the server agent instead. The API accepts http, https, ping, tcp, ssl, and dns.

Type-specific fields

HTTP / HTTPS (type: "http" or "https")

For HTTP/HTTPS, target is validated for SSRF safety on create; private/loopback targets are rejected with 422.

TCP (type: "tcp")

SSL (type: "ssl")

DNS (type: "dns")

List monitors

GET /v1/monitors

Returns all monitors owned by your team, each enriched with the latest status pulled from VictoriaMetrics.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitors": [
      {
        "id": 123,
        "type": "https",
        "name": "Marketing site",
        "target": "https://example.com",
        "interval_seconds": 60,
        "timeout_seconds": 30,
        "retry_count": 3,
        "is_active": 1,
        "current_status": "up",
        "last_status": "up",
        "last_response_time": 142,
        "last_checked_at": "2026-06-23T10:15:00Z",
        "status_class": "success",
        "uptime_percentage": 99.98
      }
    ],
    "count": 1
  }
}

last_status is pending when no checks have run yet, and unknown if metrics are temporarily unavailable.

Create a monitor

POST /v1/monitors

Send a JSON body. name, type, and target are required. Returns 201 with the created monitor.

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "type": "https",
    "target": "https://example.com",
    "interval_seconds": 60,
    "timeout_seconds": 30,
    "retry_count": 3,
    "method": "GET",
    "expected_status": 200,
    "expected_string": "Welcome",
    "follow_redirects": true,
    "headers": { "User-Agent": "StatusRadar" },
    "probe_servers": [1, 4]
  }'

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "type": "https",
      "name": "Marketing site",
      "target": "https://example.com"
    },
    "id": 123
  }
}

Validation errors return 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "type": "Invalid monitor type",
    "target": "Target is required"
  }
}

DNS example:

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MX record",
    "type": "dns",
    "target": "example.com",
    "dns_record_type": "MX",
    "dns_expected": "mail.example.com"
  }'

Get a monitor

GET /v1/monitors/{id}

Returns the monitor plus 24h/7d/30d uptime and 24h average response time.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "name": "Marketing site",
      "type": "https",
      "target": "https://example.com",
      "last_status": "up",
      "last_response_time": 142,
      "last_checked_at": "2026-06-23T10:15:00Z"
    },
    "uptime": {
      "24h": 100.0,
      "7d": 99.95,
      "30d": 99.98
    },
    "avg_response_time_ms": 138
  }
}

Returns 404 if the monitor does not exist or is not owned by your team.

Update a monitor

PUT /v1/monitors/{id}

Send only the fields you want to change. The monitor type cannot be changed; type-specific fields apply to the existing type. Returns the updated monitor.

curl -X PUT https://api.statusradar.dev/v1/monitors/123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site (prod)",
    "interval_seconds": 120,
    "is_active": false
  }'

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor": {
      "id": 123,
      "name": "Marketing site (prod)",
      "interval_seconds": 120,
      "is_active": 0
    }
  }
}

Updatable common fields: name, group_name, interval_seconds, timeout_seconds, retry_count, is_active, notify_on_failure, notify_on_recovery, plus the type-specific fields for the monitor's existing type.

Delete a monitor

DELETE /v1/monitors/{id}

curl -X DELETE https://api.statusradar.dev/v1/monitors/123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "message": "Monitor deleted successfully"
  }
}

Check history

GET /v1/monitors/{id}/checks?hours=24

Returns recent check results (default last 24 hours), newest first. Backed by VictoriaMetrics at 5-minute resolution.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.statusradar.dev/v1/monitors/123/checks?hours=48"

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "checks": [
      {
        "status": "up",
        "response_time_ms": 142,
        "status_code": 200,
        "error_message": null,
        "checked_at": "2026-06-23T10:15:00Z"
      }
    ],
    "count": 1
  }
}

Metrics

GET /v1/monitors/{id}/metrics?hours=24

Returns response-time and status time series (default last 24 hours, 5-minute step).

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.statusradar.dev/v1/monitors/123/metrics?hours=24"

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor_id": "123",
    "hours": 24,
    "response_time": [
      { "time": "2026-06-23T10:00:00Z", "value": 138 }
    ],
    "status": [
      { "time": "2026-06-23T10:00:00Z", "status": "up" }
    ]
  }
}

Uptime summary

GET /v1/monitors/{id}/uptime

Returns uptime percentages over 24h, 7d, 30d, and 90d.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors/123/uptime

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "monitor_id": "123",
    "uptime": {
      "24h": 100.0,
      "7d": 99.95,
      "30d": 99.98,
      "90d": 99.97
    }
  }
}

Public uptime endpoint

GET /v1/monitors/{id}/uptime

A public, no-authentication variant of the uptime endpoint is also exposed for embedding uptime figures on external pages. It returns the same uptime summary shape without requiring a Bearer token. Use the authenticated User API route above for programmatic access to your own monitors.

Next Steps

• API Overview — full API surface and conventions
• API Authentication — token types and how to send them
• Agent installation — set up server (agent) monitoring
• Alerts overview — route monitor failures to channels
• OTLP overview — backend traces, logs, and metrics