API Reference

Integrate StackWatch with your applications using our REST API.

Getting Started with the API

The StackWatch API provides programmatic access to all monitoring features. Use it to create monitors, retrieve status data, manage incidents, and integrate with your existing tools.

API Authentication

All API requests require authentication using API tokens. Generate tokens in your account settings and include them in the Authorization header.

Generate API Token

Go to Settings → API Tokens in your dashboard

Click "Create Token" and give it a descriptive name

Copy the token immediately - it will only be shown once

Authorization: Bearer your-api-token-here

API Endpoints

Monitors Endpoints

GET /api/monitors

Retrieve a list of all monitors in your account.

POST /api/monitors

Create a new monitor with specified configuration.

GET /api/monitors/{id}

Get detailed information about a specific monitor.

PUT /api/monitors/{id}

Update an existing monitor's configuration.

DELETE /api/monitors/{id}

Delete a monitor and all its associated data.

Status Endpoints

GET /api/status

Get overall system status and summary statistics.

GET /api/status/{monitor_id}

Get current status and recent history for a specific monitor.

Code Examples

cURL Examples

# Get all monitors
curl -X GET "https://your-domain.com/api/monitors" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Create a new monitor
curl -X POST "https://your-domain.com/api/monitors" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "My Website",
    "url": "https://example.com",
    "type": "http",
    "interval": 300
  }'

JavaScript Examples

// Fetch monitors using JavaScript
const response = await fetch('https://your-domain.com/api/monitors', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

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

// Create a monitor using JavaScript
const newMonitor = await fetch('https://your-domain.com/api/monitors', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    name: 'My API',
    url: 'https://api.example.com/health',
    type: 'http',
    interval: 60
  })
});

const monitor = await newMonitor.json();

Python Examples

import requests

# Setup headers for authentication
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}

# Get all monitors
response = requests.get('https://your-domain.com/api/monitors', headers=headers)
monitors = response.json()

# Create a new monitor
monitor_data = {
    'name': 'Database Server',
    'url': 'https://db.example.com',
    'type': 'ping',
    'interval': 120
}

response = requests.post(
    'https://your-domain.com/api/monitors',
    headers={**headers, 'Content-Type': 'application/json'},
    json=monitor_data
)

new_monitor = response.json()

Response Format

All API responses follow a consistent JSON format with data and metadata sections:

{
  "data": {
    "id": 1,
    "name": "My Website",
    "url": "https://example.com",
    "type": "http",
    "status": "up",
    "interval": 300,
    "response_time": 245,
    "uptime_percentage": 99.95,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "meta": {
    "timestamp": "2024-01-01T12:00:00Z",
    "version": "1.0"
  }
}

Rate Limiting

API requests are rate limited to ensure fair usage. Current limits are 1000 requests per hour per API token.

Rate Limit Headers

X-RateLimit-Limit: Total requests allowed per hour

X-RateLimit-Remaining: Requests remaining in current window

X-RateLimit-Reset: Time when the rate limit resets

What's Next?

Start Building

Begin integrating StackWatch into your applications.

Learn More

Explore More

Browse all documentation sections for comprehensive guides.

Learn More