API Overview - Blocklight

The REST API is optional and runs alongside the core runtime security engine. Enable it with --profile api.

When to Use the API

The API is useful for:

Dashboards & Visualization - Build custom dashboards to query historical detections, view system metrics, and monitor rule performance
Programmatic Queries - Query detections and rules programmatically from your applications or scripts
Historical Analysis - Access past detections for analysis and reporting
System Monitoring - Check system status, rule counts, and operational metrics via HTTP

Note: The core runtime security engine works standalone without the API. Real-time alerts are handled by built-in channels (Slack, Discord, Email, Webhooks), and operational monitoring is available via Prometheus metrics. Only enable the API if you need to query historical data or build custom dashboards.

Base URL

http://localhost:8000

Quick Start

# Start API
docker-compose --profile api up -d

# Test connection
curl http://localhost:8000/health

# Get system status
curl http://localhost:8000/api/v1/system/status

Response Format

All responses are JSON. Success responses include data, errors include error and details fields.

// Success
{
  "count": 10,
  "data": [...]
}

// Error
{
  "error": "Failed to get rules",
  "details": "connection timeout"
}

Authentication: Currently not required. Add authentication via reverse proxy (Nginx, Caddy) or API gateway if exposing publicly.

Rate Limiting

Default: 100 requests per minute per IP. Configure in config/config.yaml:

api:
  rate_limit:
    enabled: true
    requests_per_minute: 100

GET /health

​When to Use the API

​Base URL

​Quick Start

​Response Format

​Rate Limiting

When to Use the API

Base URL

Quick Start

Response Format

Rate Limiting