API Reference
Bhairava exposes a REST API under /api, a GraphQL endpoint at /graphql, and a WebSocket at /ws. All endpoints require a Bearer JWT except login and health.
Interactive API docs (Swagger UI) are available on any running instance at /docs, and ReDoc at /redoc.
Authentication flow
Obtain an access token from the login endpoint, then send it as a Bearer token in the Authorization header on every subsequent request.
# 1. Obtain an access token
curl -X POST https://soc.example.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"..."}'
# 2. Call authenticated endpoints with the token
curl https://soc.example.com/api/alerts \
-H "Authorization: Bearer $TOKEN"Authentication
Session lifecycle, current-user lookup, self-service registration, and multi-factor auth.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/login | Obtain a JWT access token. |
| POST | /api/auth/refresh | Exchange a refresh token for a new access token. |
| GET | /api/auth/me | Current authenticated user and roles. |
| POST | /api/auth/logout | Revoke the current session. |
| POST | /api/auth/register | Create a viewer-only account. |
| POST | /api/auth/mfa | Enroll, verify, and manage MFA under /api/auth/mfa. |
Alerts
Query, aggregate, correlate, and escalate security alerts.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/alerts | List alerts (filterable by severity, source, status, time). |
| GET | /api/alerts/stats | Volume & severity statistics. |
| POST | /api/alerts/bulk | Bulk-create alerts. |
| PATCH | /api/alerts/bulk | Bulk-update alerts. |
| GET | /api/alerts/<id>/similar | Alerts similar to the given one. |
| POST | /api/alerts/<id>/escalate-to-incident | Promote an alert to an incident. |
| GET | /api/alerts/groups | Correlated alert groups. |
Incidents
Manage incidents, their metrics, and response templates.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/incidents | List incidents. |
| GET | /api/incidents/metrics | MTTR, MTTD, and volume metrics. |
| GET | /api/incidents/<id> | Retrieve a single incident. |
| PATCH | /api/incidents/<id> | Update incident state, assignee, or notes. |
| GET | /api/incidents/templates | Response playbook templates. |
Agents & Fleet
Drive the AI agent pool and manage enrolled endpoint agents.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/agents/workers | AI agent pool status. |
| POST | /api/agents/l1/pick-next | Have an L1 agent claim the next alert. |
| POST | /api/agents/auto-run | Start the autonomous triage loop. |
| POST | /api/agents/managed/<id>/heartbeat | Endpoint agent check-in. |
| GET | /api/agents/managed/fleet/summary | Fleet health summary. |
| GET | /api/agents/managed/enrollment-tokens | List enrollment tokens. |
| GET | /api/agents/managed/setup/install.sh | Linux installer (also install.ps1, install-macos.sh, docker-compose.yml). |
Detection
Author and inspect Sigma detection rules and coverage.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/detection/rules | List detection rules. |
| POST | /api/detection/rules | Create a detection rule. |
| GET | /api/detection/active-rules | Rules currently deployed to the engine. |
| GET | /api/detection/coverage-analysis | MITRE ATT&CK coverage & gaps. |
Hunting
Generate hypotheses and run threat hunts.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/hunting/generate-hypotheses | AI-generated hunt hypotheses. |
| POST | /api/hunting/execute | Run an ad-hoc hunt query. |
| GET | /api/hunting/hunts | List saved and scheduled hunts. |
| POST | /api/hunting/hunts/<id>/execute | Execute a saved hunt. |
Forensics
Work with forensic cases and export evidence.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/forensics/cases | List forensic cases. |
| GET | /api/forensics/cases/<id> | Retrieve a case with artifacts. |
| POST | /api/forensics/cases/<id>/export | Export a case evidence bundle. |
Compliance
Assess controls against compliance frameworks.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/compliance/frameworks | List supported frameworks. |
| GET | /api/compliance/controls/<framework> | Controls for a framework. |
| POST | /api/compliance/controls/<framework>/assess | Run an assessment for a framework. |
Threat Intelligence
Look up indicators of compromise and manage feeds.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/threat-intel/ip/<ip> | Reputation & enrichment for an IP. |
| GET | /api/threat-intel/hash/<hash> | File hash reputation lookup. |
| GET | /api/threat-intel/domain/<domain> | Domain reputation lookup. |
| GET | /api/threat-intel/feeds | Configured threat intel feeds. |
MCP
Inspect Model Context Protocol servers, their tools, and health.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/mcp/servers | List MCP servers. |
| GET | /api/mcp/servers/health-overview | Aggregate server health. |
| GET | /api/mcp/tools | List all exposed MCP tools. |
| POST | /api/mcp/servers/test-connection | Test connectivity to a server. |