API Reference

📡 API Reference

Base URL: http://localhost:8000

All responses follow this envelope format:

{
  "success": true,
  "message": "Description",
  "data": { ... },
  "timestamp": "2026-08-31T10:00:00"
}

---

🩺 Health & Status

GET /health

System health check.

curl http://localhost:8000/health

{ "status": "healthy", "monitoring": true, "database": "connected" }

GET /api/v1/health

Extended health check.

GET /status

Current monitoring status.

curl http://localhost:8000/status

{
  "is_monitoring": true,
  "current_interface": "Wi-Fi",
  "alerts_generated": 47,
  "monitoring_active": true
}

POST /start-monitoring

Start packet capture and monitoring.

POST /stop-monitoring

Stop packet capture and monitoring.

---

🚨 Alerts

GET /alerts

Get alerts with optional filtering.

Query Param	Type	Description
limit	int	Max results (default: 100)
offset	int	Pagination offset
risk_level	string	Filter: low, medium, high, critical
attack_type	string	Filter by attack type

curl "http://localhost:8000/alerts?limit=10&risk_level=high"

---

📋 Logs

GET /logs

Get system logs.

Query Param	Type	Description
limit	int	Max results
level	string	INFO, WARNING, ERROR

curl "http://localhost:8000/logs?limit=20&level=ERROR"

---

📊 Statistics

GET /stats

Get system statistics.

curl http://localhost:8000/stats

Returns packet counts, attack type distribution, top IPs, protocol breakdown.

---

🚫 Blacklist

GET /blacklist

Get all blacklisted IPs.

POST /blacklist

Add IP to blacklist.

curl -X POST http://localhost:8000/blacklist \
  -H "Content-Type: application/json" \
  -d '{"ip_address": "198.51.100.1", "reason": "Malicious activity", "risk_level": "high"}'

DELETE /blacklist/{ip_address}

Remove IP from blacklist.

curl -X DELETE http://localhost:8000/blacklist/198.51.100.1

POST /check-ip

Check IP reputation (JSON body).

curl -X POST http://localhost:8000/check-ip \
  -H "Content-Type: application/json" \
  -d '{"ip_address": "8.8.8.8"}'

GET /check-ip/{ip_address}

Check IP reputation (URL path).

curl http://localhost:8000/check-ip/8.8.8.8

---

🏢 Organizations (Admin)

GET /api/v1/organizations/

List all organizations.

POST /api/v1/organizations/

Create a new organization.

{
  "name": "Acme Security",
  "slug": "acme-security",
  "description": "Primary SOC org",
  "plan": "enterprise"
}

POST /api/v1/organizations/{id}/suspend

Suspend an organization.

POST /api/v1/organizations/{id}/activate

Activate a suspended organization.

---

👤 Users (Admin)

GET /api/v1/users/

List all users.

POST /api/v1/users/

Create a new user.

{
  "email": "analyst@company.com",
  "name": "Security Analyst",
  "role": "security_analyst",
  "org_id": "org-id-here"
}

PUT /api/v1/users/{user_id}

Update user role or status.

{ "role": "admin", "is_active": true }

DELETE /api/v1/users/{user_id}

Delete a user.

---

📝 Audit Logs (Admin)

GET /api/v1/audit-logs/

Get audit logs with optional filtering.

Query Param	Type	Description
action	string	Filter by action type
user_id	string	Filter by user
date_from	string	Start date (YYYY-MM-DD)
date_to	string	End date (YYYY-MM-DD)

POST /api/v1/audit-logs/

Record an audit event.

{
  "action": "firewall_rule_created",
  "resource_type": "firewall_rule",
  "resource_id": "rule-42",
  "details": { "port": 8080 }
}

---

📤 Exports

GET /export/alerts

Export alerts as CSV file.

GET /api/v1/reports/audit-logs/export

Export audit logs as CSV file.

POST /api/v1/reports/generate

Generate a full system report.

---

🔌 WebSocket

WS /ws

Real-time event stream.

const ws = new WebSocket("ws://localhost:8000/ws");
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.type: "alert" | "status" | "stats" | "log" | "connection"
};