API Reference

API Reference

Base URL: http://localhost:8000 (self-hosted) or your deployed instance

All endpoints (except /health, /auth/register, /auth/login) require authentication.

---

Authentication

Register

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "full_name": "Jane Doe",
  "organization_name": "Acme Corp"
}

Login

POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=SecurePass123!

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

Access tokens expire in 30 minutes. Refresh tokens expire in 7 days.

Get Current User

GET /auth/me
Authorization: Bearer <access_token>

Update Profile

PATCH /auth/me
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "full_name": "Jane Smith",
  "email": "jane@example.com"
}

Change Password

PUT /auth/me/password
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "current_password": "OldPass123!",
  "new_password": "NewPass456!"
}

Get Organization

GET /auth/organization
Authorization: Bearer <access_token>

Update Organization

PATCH /auth/organization
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "Acme Corp",
  "alert_email": "security@acme.com"
}

Requires admin role.

---

Agents

Create Agent

POST /agents/
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "My Laptop"
}

Response includes api_key — shown only once, store it immediately.

List Agents

GET /agents/
Authorization: Bearer <access_token>

Delete Agent

DELETE /agents/{agent_id}
Authorization: Bearer <access_token>

Agent Heartbeat (Agent → Backend)

POST /agents/heartbeat
X-API-Key: mcp_sk_<key>
Content-Type: application/json

{
  "hostname": "laptop.local",
  "os_type": "windows",
  "username": "jane",
  "agent_version": "0.1.2"
}

---

MCP Servers

Report Servers (Agent → Backend)

POST /mcp/report
X-API-Key: mcp_sk_<key>
Content-Type: application/json

{
  "servers": [
    {
      "server_name": "filesystem",
      "server_type": "@modelcontextprotocol/server-filesystem",
      "command": "npx @modelcontextprotocol/server-filesystem /home",
      "scope": "/home",
      "env_vars": ["PATH", "HOME"]
    }
  ]
}

List Servers

GET /mcp/servers?risk_level=high&status=active&search=postgres&page=1&page_size=25
Authorization: Bearer <access_token>

Query parameters:

Param	Type	Description
risk_level	string	Filter: critical, high, medium, low
status	string	Filter: active, dormant
agent_id	uuid	Filter by specific agent
search	string	Search server names
page	int	Page number (default: 1)
page_size	int	Results per page (default: 25)

Get Server Details

GET /mcp/servers/{server_id}
Authorization: Bearer <access_token>

Update Server (Mark Verified)

PATCH /mcp/servers/{server_id}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "is_verified": true
}

---

Dashboard

Stats

GET /dashboard/stats
Authorization: Bearer <access_token>

Response:

{
  "total_servers": 47,
  "critical_count": 2,
  "high_count": 5,
  "medium_count": 18,
  "low_count": 22,
  "active_agents": 12,
  "unresolved_alerts": 3
}

Risk Distribution

GET /dashboard/risk-distribution
Authorization: Bearer <access_token>

Top Risks

GET /dashboard/top-risks?limit=5
Authorization: Bearer <access_token>

---

Alerts

List Alerts

GET /alerts/?dismissed=false&severity=critical
Authorization: Bearer <access_token>

Dismiss Alert

POST /alerts/{alert_id}/dismiss
Authorization: Bearer <access_token>

Dismiss All Alerts

POST /alerts/dismiss-all
Authorization: Bearer <access_token>

---

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "0.1.2",
  "database": "connected"
}