Sentinel API Reference (v2026.06.024)¶

Complete API documentation for plugins, agents, and external integrations.

Authentication¶

Three authentication methods are supported:

API keys are created by a superadmin in Settings → REST API Keys. Each key carries fine-grained scopes (legacy read/write/admin keys remain valid):

CSRF: browser-session POST/PUT/DELETE requests require the X-CSRF-Token header (the web UI adds it automatically via a global fetch wrapper). Bearer-token calls are exempt.

2FA: if TOTP is enrolled for the user, POST /api/login is followed by a second step with the 6-digit code. Manage via /api/2fa/status|setup|enable|disable.

Brute-force protection: 5 failed logins → IP banned 300 s. /api/analyze/* endpoints are rate-limited to 10 req/min per IP.

Plugin API (internal — api.py)¶

Used by detector plugins running inside the Sentinel process.

report_problem(key, data)¶

Create or update an incident. Same key = update last_seen and reset missing_count.

api.report_problem("DISK_FULL|proxmox01|/data", {
    "status": "active",
    "last_line": "Disk /data 92% full",
    "channel_type": "infra",       # infra | security | agents | root
    "severity": "CRITICAL",        # INFO | WARNING | CRITICAL
    "host": "proxmox01",
    "cluster": "proxmox01",
    "log_file": "/var/log/sentinel/logs/capacity.log",
    "last_seen": datetime.now(timezone.utc).isoformat(),
    "missing_count": 0
})

resolve_problem(key)¶

Close an incident. Emits a WebSocket resolve event to all connected clients.

api.resolve_problem("DISK_FULL|proxmox01|/data")

get_problem(key) → dict | None¶

Return the current DB row for a key, or None if it doesn't exist.

enqueue_ai_task(prompt, channel)¶

Push a task to the AI worker queue. Non-blocking.

api.enqueue_ai_task(
    f"Analyse this SSH attack: {log_line}",
    channel="security"
)

save_telemetry_snapshot(metric, value, host)¶

Write a time-series data point. Writes are buffered and flushed in batches (and on SIGTERM).

api.save_telemetry_snapshot("cpu_usage", 94.2, "hpc-node-01")

get_infrastructure_label(file_path) → str¶

Extract the SERVER: <hostname> context injected by Overhealth, or derive from file path.

add_root_audit(server, ip)¶

Idempotent root-session audit entry (one active record per server+ip) with reverse DNS lookup.

notifier.send_notification(title, message, severity, channel)¶

Standalone fan-out to all enabled outbound channels with retry queue and per-severity throttling. See Programmer Documentation.

REST API (HTTP)¶

Base URL: http://<host>:5050

Authentication¶

POST /api/login
Content-Type: application/json

{"username": "admin", "password": "secret"}

Response sets Set-Cookie: session=... (HMAC-signed; absolute session timeout 12 h). If the account has TOTP enrolled, the response requests a second step with the 6-digit code.

2FA / TOTP¶

Issues¶

Agents¶

Agent ingest payload¶

POST /api/v1/agent/ingest
Authorization: Bearer <agent_token>
Content-Type: application/json

{
  "hostname": "hpc-node-04",
  "version": "a3f8c12",
  "channel": "agents",
  "ip_addresses": ["10.0.0.4"],
  "timestamp": "2026-06-02T18:42:00+02:00",
  "data": {
    "cpu": 94.2,
    "message": "CPU critical: 94.2%",
    "severity": "CRITICAL"
  },
  "metrics": { "cpu_pct": 94.2, "ram_pct": 61.0, "disk_pct": 72.5 }
}

The optional metrics object is evaluated against agent_thresholds rules — issues are created on breach and auto-resolved on recovery.

Autofix Actions & SSH¶

Analytics & Reports¶

System, Configuration & Admin¶

Topology¶

Export, Inbound Webhooks & Integrations¶

Inbound webhook auth supports Bearer token or HMAC X-Hub-Signature-256 + X-Webhook-Timestamp (replay protection).

Outbound lifecycle webhooks fire on issue CREATED / ACKNOWLEDGED / RESOLVED; critical issues can sync to Gitea and annotate Grafana dashboards.

Prometheus metrics¶

# GAUGE: active incidents per channel
sentinel_issues_total{channel="infra"} 3
sentinel_issues_total{channel="security"} 1

# GAUGE: agents online
sentinel_agents_online 12

# GAUGE: AI worker queue depth
sentinel_queue_depth 2

# GAUGE: AI response latency (seconds)
sentinel_ai_latency_seconds 1.24

# GAUGE: log parser throughput
sentinel_lines_parsed_per_min 1840

Self-metrics can also be pushed to a Prometheus pushgateway (prometheus.pushgateway_url).

API Documentation (auto-generated)¶

WebSocket Events (Socket.IO)¶

Connect to ws://<host>:5050/socket.io/. Transport order is ['polling', 'websocket'] with upgrade — works behind any reverse proxy. Server-side the frontend queue is bounded (500, drop-oldest) and duplicate messages within 1 s are deduplicated.