API Overview

StatusRadar provides a comprehensive REST API for programmatic access to monitoring data, server management, and incident tracking.

Base URL

All API requests should be made to:

https://api.statusradar.dev/v1

API Versions

Current API version: v1

The version is included in the URL path. Future versions will be released under new paths (v2, v3, etc.) while maintaining backwards compatibility with v1.

Authentication

All API requests require authentication using Bearer tokens.

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

See API Authentication for details.

Request Format

HTTP Methods

The API follows REST conventions:

GET - Retrieve resources
POST - Create new resources
PUT - Update existing resources (full replacement)
PATCH - Partially update resources
DELETE - Delete resources

Content Type

All POST, PUT, and PATCH requests must include:

Content-Type: application/json

Request body should be valid JSON.

Response Format

Success Responses

Successful requests return JSON with HTTP status 200-299:

Single Resource:

{
  "data": {
    "id": 123,
    "name": "Production Web Server",
    "status": "online",
    "created_at": "2025-10-15T10:30:00Z"
  }
}

Collection:

{
  "data": [
    {
      "id": 123,
      "name": "Server 1"
    },
    {
      "id": 124,
      "name": "Server 2"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 20
  }
}

Creation/Update:

{
  "success": true,
  "message": "Resource created successfully",
  "data": {
    "id": 125,
    ...
  }
}

Error Responses

Error responses include HTTP status 400-599 and JSON error details:

{
  "error": true,
  "message": "Resource not found",
  "code": "not_found",
  "status": 404
}

Common error codes:

400 - Bad Request (invalid parameters)
401 - Unauthorized (missing or invalid token)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource doesn't exist)
422 - Unprocessable Entity (validation failed)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Pagination

List endpoints support pagination using query parameters:

GET /v1/monitors?page=2&per_page=50

Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 2,
    "per_page": 50,
    "total_pages": 3
  },
  "links": {
    "first": "/v1/monitors?page=1",
    "prev": "/v1/monitors?page=1",
    "next": "/v1/monitors?page=3",
    "last": "/v1/monitors?page=3"
  }
}

Filtering and Sorting

Filtering

Most list endpoints support filtering:

# Filter by status
GET /v1/monitors?status=online

# Filter by type
GET /v1/monitors?type=http

# Multiple filters
GET /v1/monitors?status=online&type=http

Sorting

Use sort parameter:

# Sort by name ascending
GET /v1/monitors?sort=name

# Sort by created date descending
GET /v1/monitors?sort=-created_at

# Multiple sort fields
GET /v1/monitors?sort=status,-created_at

Prefix with - for descending order.

Rate Limiting

API requests are rate limited to prevent abuse.

Limits:

Authenticated requests: 1000 requests per hour per API token
Unauthenticated requests: 100 requests per hour per IP address

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 945
X-RateLimit-Reset: 1697457600

When rate limit is exceeded, API returns HTTP 429:

{
  "error": true,
  "message": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "status": 429,
  "retry_after": 3600
}

Best practices:

Cache responses when possible
Use webhooks instead of polling
Respect X-RateLimit-Remaining header
Implement exponential backoff for retries

Available Endpoints

Monitors

Manage HTTP, TCP, ping, SSL, DNS, and server monitors.

GET    /v1/monitors              # List all monitors
GET    /v1/monitors/{id}         # Get monitor details
POST   /v1/monitors              # Create monitor
PUT    /v1/monitors/{id}         # Update monitor
DELETE /v1/monitors/{id}         # Delete monitor
GET    /v1/monitors/{id}/checks  # Get check history
GET    /v1/monitors/{id}/metrics # Get performance metrics

See Monitors API for details.

Incidents

Track and manage service incidents.

GET    /v1/incidents             # List incidents
GET    /v1/incidents/{id}        # Get incident details
POST   /v1/incidents             # Create incident
PUT    /v1/incidents/{id}        # Update incident
POST   /v1/incidents/{id}/updates # Add incident update

See Incidents API for details.

Status Pages

Manage public status pages.

GET    /v1/status-pages          # List status pages
GET    /v1/status-pages/{id}     # Get status page details
POST   /v1/status-pages          # Create status page
PUT    /v1/status-pages/{id}     # Update status page
DELETE /v1/status-pages/{id}     # Delete status page

See Status Pages API for details.

Data Types

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

{
  "created_at": "2025-10-15T10:30:00Z",
  "updated_at": "2025-10-15T11:45:00Z"
}

Booleans

Boolean values are true or false (lowercase):

{
  "enabled": true,
  "ssl_verify": false
}

Numbers

Integers and floats are used as appropriate:

{
  "interval": 300,          // integer (seconds)
  "timeout": 30,            // integer (seconds)
  "uptime_percent": 99.95,  // float
  "response_time": 123.45   // float (milliseconds)
}

Enumerations

Enum values are lowercase strings:

{
  "type": "http",              // http, https, tcp, ping, ssl, dns, server
  "status": "online",          // online, offline, pending, paused
  "method": "get",             // get, post, put, patch, delete
  "alert_channel": "email"     // email, slack, webhook, telegram, discord
}

CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based requests.

Allowed origins: All origins (*)

Allowed methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

Allowed headers: Content-Type, Authorization

Webhooks

StatusRadar can send webhook notifications for events:

Monitor status changes (online → offline)
Incident created/updated
Alert triggered

Webhook payload example:

{
  "event": "monitor.status_changed",
  "timestamp": "2025-10-15T12:00:00Z",
  "data": {
    "monitor_id": 123,
    "monitor_name": "Production API",
    "old_status": "online",
    "new_status": "offline",
    "response_time": null,
    "error_message": "Connection timeout"
  }
}

Configure webhooks in Dashboard → Settings → Integrations.

SDKs and Libraries

Official Libraries

Coming soon:

Python SDK
JavaScript/TypeScript SDK
Go SDK
PHP SDK

Community Libraries

Currently, use any HTTP client library to interact with the API.

Example (Python):

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}

# List monitors
response = requests.get(
    'https://api.statusradar.dev/v1/monitors',
    headers=headers
)

monitors = response.json()
print(monitors)

Example (curl):

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

Example (JavaScript):

const response = await fetch('https://api.statusradar.dev/v1/monitors', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const monitors = await response.json();
console.log(monitors);

Testing

Sandbox Environment

Use production API for testing. All data is isolated per account.

Best practices:

Create test monitors with unique names (prefix: [TEST])
Use development API tokens (separate from production)
Clean up test resources after testing

API Explorer

Coming soon: Interactive API explorer in dashboard.

Best Practices

1. Use Appropriate HTTP Methods

# ✅ Good - proper method for operation
POST /v1/monitors        # Create
GET  /v1/monitors/{id}   # Read
PUT  /v1/monitors/{id}   # Update (full)
PATCH /v1/monitors/{id}  # Update (partial)
DELETE /v1/monitors/{id} # Delete

# ❌ Bad - wrong method
GET /v1/monitors/create
POST /v1/monitors/{id}/update

2. Handle Errors Gracefully

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 429:
        # Rate limited - wait and retry
        time.sleep(60)
        retry_request()
    elif e.response.status_code == 404:
        # Resource not found
        handle_not_found()
    else:
        # Other error
        log_error(e)

3. Implement Retry Logic

from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('https://', adapter)

response = session.get(url, headers=headers)

4. Use Pagination Efficiently

def get_all_monitors():
    monitors = []
    page = 1

    while True:
        response = requests.get(
            f'https://api.statusradar.dev/v1/monitors?page={page}&per_page=100',
            headers=headers
        )
        data = response.json()

        monitors.extend(data['data'])

        if page >= data['meta']['total_pages']:
            break

        page += 1

    return monitors

5. Cache Responses

import time

cache = {}
CACHE_TTL = 300  # 5 minutes

def get_monitors_cached():
    cache_key = 'monitors'

    if cache_key in cache:
        data, timestamp = cache[cache_key]
        if time.time() - timestamp < CACHE_TTL:
            return data

    response = requests.get(url, headers=headers)
    data = response.json()

    cache[cache_key] = (data, time.time())
    return data

6. Validate Input

Always validate data before sending to API:

def create_monitor(name, url, type='http'):
    # Validate required fields
    if not name or not url:
        raise ValueError('Name and URL are required')

    # Validate URL format
    if not url.startswith(('http://', 'https://')):
        raise ValueError('Invalid URL format')

    # Validate enum values
    if type not in ['http', 'https', 'tcp', 'ping', 'ssl', 'dns']:
        raise ValueError('Invalid monitor type')

    # Send request
    ...

Support

Getting Help

Documentation: https://statusradar.dev/docs
API Status: https://status.statusradar.dev
Support Email: [email protected]
Community: https://community.statusradar.dev

Reporting Issues

For API bugs or feature requests:

Check existing documentation
Search community forums
Contact support with:
- Request/response details
- Error messages
- Expected vs actual behavior
- Steps to reproduce

Changelog

v1.0.0 (Current)

Released: October 2025

Features:

Complete REST API
Monitor management
Incident tracking
Status pages
Rate limiting
Pagination
Filtering and sorting

Coming Soon:

Webhooks v2 (enhanced payloads)
API Explorer
Official SDKs
GraphQL API (under consideration)

Next Steps

API Authentication - Learn about tokens and auth
Monitors API - Manage monitors programmatically
Incidents API - Track and manage incidents

On this page

Base URL
API Versions
Authentication
Request Format
HTTP Methods
Content Type
Response Format
Success Responses
Error Responses
Pagination
Filtering and Sorting
Filtering
Sorting
Rate Limiting
Available Endpoints
Monitors
Incidents
Status Pages
Data Types
Timestamps
Booleans
Numbers
Enumerations
CORS
Webhooks
SDKs and Libraries
Official Libraries
Community Libraries
Testing
Sandbox Environment
API Explorer
Best Practices
1. Use Appropriate HTTP Methods
2. Handle Errors Gracefully
3. Implement Retry Logic
4. Use Pagination Efficiently
5. Cache Responses
6. Validate Input
Support
Getting Help
Reporting Issues
Changelog
v1.0.0 (Current)
Next Steps