Everything in the Reef dashboard is built on a JSON API under /api/. This page lists the routes for anyone who wants to query or automate Reef directly.
Authentication
Reef uses two kinds of authentication:
- Dashboard routes use your logged-in session, the same as the web interface. Requests that change data (
POST) also need Django’s CSRF token. Unauthenticated requests receive a 401 JSON response.
- Agent and monitoring routes use an API key from
DJANGO_API_KEYS, sent in the X-API-Key header.
API keys do not grant access to the dashboard routes. Findings, scans, and notifications require a logged-in session.
Health and monitoring
| Route |
Auth |
Purpose |
GET /api/health/ |
None |
Liveness check for load balancers and container health checks. |
GET /api/status/ |
API key |
Readiness check. Returns 503 if the database is unreachable. |
GET /api/ping/ |
API key |
Confirms an API key is valid. |
GET /api/whoami/ |
Session |
Returns the logged-in user. |
Findings
| Route |
Purpose |
GET /api/findings/ |
List findings. KEV findings are listed first. |
GET /api/findings/<id>/ |
One finding, with full detail. |
POST /api/findings/<id>/status/ |
Set one finding’s status. Body: {"status": "acknowledged"} |
POST /api/findings/bulk-status/ |
Set the status of up to 1,000 findings. Body: {"ids": [1, 2, 3], "status": "resolved"}. Unknown IDs are skipped. |
Valid statuses are open, acknowledged, resolved, and suppressed.
Filters for GET /api/findings/:
| Parameter |
Values |
status |
open, acknowledged, resolved, suppressed, or active (open and acknowledged) |
severity |
info, low, medium, high, critical |
scan_type |
fim, auditd, lynis, clamav, openscap, grype, yara |
agent |
Agent name |
kev |
1 to show only CISA KEV findings |
page |
Page number |
Scans
| Route |
Purpose |
GET /api/scans/ |
List scans. Filter with type and status. |
POST /api/scans/ |
Start a scan. Body: {"scan_type": "lynis", "agent": "web01", "params": {}}. params is optional. If you omit agent, the next agent to check in runs the scan. |
GET /api/scans/<id>/ |
One scan, with its summary. |
POST /api/scans/<id>/cancel/ |
Cancel a pending or running scan. |
GET /api/scans/<id>/raw/ |
The scan tool’s raw output. |
GET /api/scans/<id>/export/md/ |
Scan report in Markdown. |
GET /api/scans/<id>/export/txt/ |
Scan report in plain text. |
GET /api/scans/<id>/checklist/ |
OpenSCAP results as a STIG Viewer .cklb checklist. |
GET / POST /api/scheduler/ |
Read or set the global schedule pause. Body: {"paused": true} |
Agents
| Route |
Purpose |
GET /api/agents/ |
Every agent, with its last scan of each type and latest resource sample. |
GET /api/agents/<name>/ |
One agent’s 24-hour resource summary and its 25 most recent scans. |
GET /api/agents/<name>/metrics/?hours=24 |
Resource history and scan times for the last hours (up to 720). |
Notifications
| Route |
Purpose |
GET /api/notifications/ |
The notification feed. Add ?unread=1 for unread only. |
GET /api/notifications/unread-count/ |
The unread count shown on the bell icon. |
POST /api/notifications/<id>/read/ |
Mark one notification read. |
POST /api/notifications/read-all/ |
Mark all notifications read. |
AI interpretation
Available only when OLLAMA_ENABLED=true.
| Route |
Purpose |
POST /api/scans/<id>/interpret/ |
Request a plain-language summary of a scan. |
GET /api/scans/<id>/interpretation/ |
Retrieve the scan summary. |
POST /api/findings/<id>/interpret/ |
Request a plain-language summary of a finding. |
GET /api/findings/<id>/interpretation/ |
Retrieve the finding summary. |
