Monitors API

Create, update, and manage monitors programmatically. Supports all 13 monitor types including traditional (HTTP, TCP, ICMP) and Web3 (gas price, wallet, etc.).

List Monitors

GET /v1/monitors

# Query parameters:
?status=up          # Filter by status (up, down, paused)
?type=http          # Filter by type
?page=1&limit=20    # Pagination

Response

{
  "data": [
    {
      "id": "mon_abc123",
      "name": "Production API",
      "type": "http",
      "status": "up",
      "url": "https://api.example.com/health",
      "interval": 60,
      "timeout": 30,
      "locations": ["us-east", "eu-west"],
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-02-13T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Get Monitor

GET /v1/monitors/:id

# Example:
GET /v1/monitors/mon_abc123

Response

{
  "id": "mon_abc123",
  "name": "Production API",
  "type": "http",
  "status": "up",
  "config": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "headers": {"Authorization": "Bearer xyz"},
    "expectedStatus": 200,
    "timeout": 30
  },
  "interval": 60,
  "locations": ["us-east", "eu-west"],
  "stats": {
    "uptime": 99.8,
    "avgLatency": 245,
    "checksToday": 1440
  },
  "createdAt": "2026-01-15T10:00:00Z"
}

Create Monitor

HTTP Monitor

POST /v1/monitors
Content-Type: application/json

{
  "name": "API Health Check",
  "type": "http",
  "config": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatus": 200,
    "timeout": 30
  },
  "interval": 60,
  "locations": ["us-east"]
}

Web3 Gas Monitor

POST /v1/monitors
Content-Type: application/json

{
  "name": "Ethereum Gas Price",
  "type": "gas_price",
  "config": {
    "chain": "ethereum",
    "rpcUrl": "https://eth.llamarpc.com",
    "thresholds": {
      "high": 50,
      "low": 10
    }
  },
  "interval": 300
}

Response (201 Created)

{
  "id": "mon_xyz789",
  "name": "API Health Check",
  "type": "http",
  "status": "up",
  "createdAt": "2026-02-13T12:30:00Z"
}

Update Monitor

PUT /v1/monitors/:id
Content-Type: application/json

{
  "name": "Updated Name",
  "interval": 120,
  "config": {
    "timeout": 60
  }
}

Response

{
  "id": "mon_abc123",
  "name": "Updated Name",
  "interval": 120,
  "updatedAt": "2026-02-13T12:35:00Z"
}

Delete Monitor

DELETE /v1/monitors/:id

# Response: 204 No Content

Test Monitor

Test a monitor configuration before creating:

POST /v1/monitors/test
Content-Type: application/json

{
  "type": "http",
  "config": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "timeout": 10
  }
}

Response

{
  "success": true,
  "responseTime": 234,
  "statusCode": 200,
  "message": "Monitor test successful"
}

Get Monitor Results

GET /v1/monitors/:id/results

# Query parameters:
?from=2026-02-10T00:00:00Z    # Start time
?to=2026-02-13T23:59:59Z      # End time
?location=us-east             # Filter by location
?limit=100                    # Max results

Response

{
  "data": [
    {
      "timestamp": "2026-02-13T12:00:00Z",
      "status": "up",
      "responseTime": 245,
      "location": "us-east",
      "statusCode": 200
    },
    {
      "timestamp": "2026-02-13T11:59:00Z",
      "status": "up",
      "responseTime": 238,
      "location": "us-east",
      "statusCode": 200
    }
  ],
  "meta": {
    "total": 1440,
    "from": "2026-02-10T00:00:00Z",
    "to": "2026-02-13T23:59:59Z"
  }
}

Pause/Resume Monitor

Pause

POST /v1/monitors/:id/pause

# Response: 200 OK
{
  "id": "mon_abc123",
  "status": "paused",
  "pausedAt": "2026-02-13T12:40:00Z"
}

Resume

POST /v1/monitors/:id/resume

# Response: 200 OK
{
  "id": "mon_abc123",
  "status": "up",
  "resumedAt": "2026-02-13T12:45:00Z"
}

Silence Alerts

POST /v1/monitors/:id/silence
Content-Type: application/json

{
  "duration": 3600,  # Seconds
  "reason": "Scheduled maintenance"
}

# Response: 200 OK
{
  "silencedUntil": "2026-02-13T13:45:00Z",
  "reason": "Scheduled maintenance"
}

Monitor Types

Error Responses

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid monitor configuration",
  "details": {
    "url": "URL is required for HTTP monitors"
  },
  "status": 400
}

404 Not Found

{
  "error": "Not Found",
  "message": "Monitor not found",
  "status": 404
}

Code Examples

Python SDK

from blacktide import Client

client = Client(api_token="YOUR_TOKEN")

# Create monitor
monitor = client.monitors.create({
    "name": "API Health",
    "type": "http",
    "config": {
        "url": "https://api.example.com/health"
    },
    "interval": 60
})

# List monitors
monitors = client.monitors.list(status="up")

# Update monitor
client.monitors.update(monitor.id, {"interval": 120})

# Delete monitor
client.monitors.delete(monitor.id)

JavaScript/TypeScript SDK

import { BlackTide } from '@blacktide/sdk';

const client = new BlackTide('YOUR_TOKEN');

// Create monitor
const monitor = await client.monitors.create({
  name: 'API Health',
  type: 'http',
  config: { url: 'https://api.example.com/health' },
  interval: 60
});

// Get results
const results = await client.monitors.getResults(monitor.id, {
  from: '2026-02-10T00:00:00Z',
  to: '2026-02-13T23:59:59Z'
});

Next Steps

• Incidents API: Query and manage incidents
• Alerts API: Configure alert rules
• HTTP Monitor: Detailed HTTP configuration
• Web3 Monitors: Gas price, wallet, contract events