Monitors API

Create, update, and manage monitors programmatically. Supports all 9 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

Type	Description	Config Fields
`http`	HTTP/HTTPS endpoints	url, method, headers, body, expectedStatus
`tcp`	TCP port checks	host, port
`icmp`	Ping checks	host
`tls`	SSL certificate	domain, expiryDays
`heartbeat`	Cron jobs / scheduled tasks (push-based)	expectedInterval, gracePeriod
`prometheus`	Prometheus Remote Write ingestion	ingestUrl, authToken, labelFilters
`opentelemetry`	OTLP metrics ingestion (gRPC or HTTP)	otlpProtocol, endpoint, resourceAttributes
`web3`	Umbrella Web3 monitor (uses `config.subType` for gas_price, whale_wallet, liquidation, defi_protocol, subgraph or bridge)	subType + subtype-specific fields
`web3_contract_event`	Smart contract event tracking	chainId, address, abi, eventName

BlackTide exposes 9 user-creatable monitor types: 5 traditional (http, tcp, icmp, tls, heartbeat), 2 metrics ingestion (prometheus, opentelemetry) and 2 Web3 (web3 — which covers all 7 Web3 subtypes — and web3_contract_event).

An additional internal type agent_metrics exists in the data model for metrics produced by the BlackTide Kubernetes agent, but it is created automatically by the platform and is not exposed in the public API.

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