API Reference

API Reference

The backend exposes a REST API at http://localhost:8000. Full interactive docs available at http://localhost:8000/docs.

---

Events

POST /api/events

Ingest a detection event from the agent.

Request body:

{
  "host_id": "ATOMIC",
  "timestamp": "2026-04-27T12:00:00Z",
  "event_type": "CANARY_TOUCHED",
  "severity": "CRITICAL",
  "pid": 1234,
  "process_name": "python3",
  "file_path": "/home/mohammad/Documents/AAA_001.txt",
  "lineage_score": 75.5,
  "entropy_delta": 4.2,
  "canary_hit": true,
  "details": {}
}

GET /api/events

List events with optional filters.

Query Param	Type	Description
host_id	string	Filter by host
severity	string	Filter by severity
event_type	string	Filter by event type
limit	int	Max results (default 50, max 500)
offset	int	Pagination offset

---

Alerts

GET /api/alerts

List alerts with optional filters.

Query Param	Type	Description
host_id	string	Filter by host
severity	string	Filter by severity
acknowledged	bool	Filter by acknowledgment status
limit	int	Max results (default 50, max 500)

GET /api/alerts/counts

Returns exact active (unacknowledged) alert counts by severity.

Response:

{
  "CRITICAL": 2,
  "HIGH": 5,
  "MEDIUM": 12,
  "LOW": 0,
  "TOTAL": 19
}

PATCH /api/alerts/{alert_id}/acknowledge

Acknowledge an alert. Automatically triggers host risk score recalculation.

POST /api/alerts/{alert_id}/analyze

Trigger on-demand AI analysis for an alert. Result is published via WebSocket.

GET /api/alerts/{alert_id}/evidence

Get all forensic evidence captured for an alert.

GET /api/alerts/{alert_id}/forensic-export

Export full alert + evidence as JSON for incident response.

---

Hosts

GET /api/hosts

List all registered hosts.

GET /api/hosts/{host_id}/risk

Get risk summary for a host including alert counts by severity and recent critical events.

POST /api/hosts/{host_id}/contain

Mark a host as administratively contained.

DELETE /api/hosts/{host_id}/contain

Release a host from containment.

---

AI

POST /api/ai/health

Trigger an AI system health check.

Request body:

{
  "events": [ ... ]
}

Result is published to rsentry:ai WebSocket channel as a health_analysis message.

---

WebSocket

WS /ws/alerts

Subscribe to live events. Receives messages on three Redis channels:

Message type	Channel	Payload
new_event	rsentry:events	Event data
new_alert	rsentry:alerts	Alert data
ai_analysis	rsentry:ai	AI classification result
health_analysis	rsentry:ai	System health check result
alert_acked	rsentry:alerts	Alert acknowledgment notification
alerts_acked	rsentry:alerts	Bulk acknowledgment (post-containment)

---

Health Check

GET /health

Simple health check endpoint. Returns {"status": "ok"}.