v2.1 REST API

API Documentation

Integrate CVEasy AI into your security stack. Full REST API for CVE intelligence, triage workflows, scanner imports, report generation, and AI-powered chat.

Base URL: http://localhost:3001 | Format: JSON | Open Swagger UI

Authentication

When deployed in production mode, all API requests require an access token. In local mode (the default), no authentication is required.

Pass your token via either the Authorization header or the X-Access-Token header:

Authorization Header

Authorization: Bearer YOUR_ACCESS_TOKEN

Alternative: X-Access-Token Header

X-Access-Token: YOUR_ACCESS_TOKEN

Access tokens are set during initial setup

Configure your access token during the setup wizard or via POST /api/config/deployment. The token is hashed with Argon2 and never stored in plain text.

Quick Start

Get started with the CVEasy AI API in seconds. Here are examples in common languages:

# Search for a CVE
curl http://localhost:3001/api/cves/search?q=CVE-2024-3094

# Get CVE detail with all enrichment data
curl http://localhost:3001/api/cves/CVE-2024-3094

# Generate AI remediation guide
curl -X POST http://localhost:3001/api/cves/CVE-2024-3094/remediate?mode=balanced

# Get top risk CVEs
curl http://localhost:3001/api/cves/top-risk?limit=10

# Upload a Nessus scan
curl -X POST http://localhost:3001/api/scanner/import \
  -F "file=@scan-results.nessus"

# Get SLA dashboard metrics
curl http://localhost:3001/api/metrics/summary

# With authentication (production mode)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://your-instance.example.com/api/cves/top-risk

import requests

BASE_URL = "http://localhost:3001"
# TOKEN = "your-access-token"  # Uncomment for production
# headers = {"Authorization": f"Bearer {TOKEN}"}

# Search for a CVE
resp = requests.get(f"{BASE_URL}/api/cves/search", params={"q": "CVE-2024-3094"})
cves = resp.json()["cves"]
print(f"Found {len(cves)} results")

# Get full CVE detail
cve = requests.get(f"{BASE_URL}/api/cves/CVE-2024-3094").json()
print(f"{cve['id']}: {cve['severity']} (CVSS {cve['cvssScore']})")
print(f"  KEV: {cve['isKev']} | EPSS: {cve['epssScore']} | TRIS: {cve['remedioScore']}")

# Generate remediation
remediation = requests.post(
    f"{BASE_URL}/api/cves/CVE-2024-3094/remediate",
    params={"mode": "balanced"}
).json()
print(remediation["remediation"])

# Upload a Nessus scan file
with open("scan.nessus", "rb") as f:
    result = requests.post(
        f"{BASE_URL}/api/scanner/import",
        files={"file": f}
    ).json()
    print(f"Imported {result['totalFindings']} findings")

# Get SLA metrics
metrics = requests.get(f"{BASE_URL}/api/metrics/summary").json()
m = metrics["metrics"]
print(f"SLA Compliance: {m['slaComplianceRate']*100:.0f}% | MTTR: {m['avgTimeToRemediate']} days")

const BASE_URL = "http://localhost:3001";
// const TOKEN = "your-access-token"; // Uncomment for production
// const headers = { Authorization: `Bearer ${TOKEN}` };

// Search for a CVE
const searchResp = await fetch(`${BASE_URL}/api/cves/search?q=CVE-2024-3094`);
const { cves } = await searchResp.json();
console.log(`Found ${cves.length} results`);

// Get CVE detail
const cve = await fetch(`${BASE_URL}/api/cves/CVE-2024-3094`).then(r => r.json());
console.log(`${cve.id}: ${cve.severity} | TRIS: ${cve.remedioScore}`);

// Generate remediation (streaming)
const stream = await fetch(`${BASE_URL}/api/cves/CVE-2024-3094/remediate/stream`, {
  method: "POST",
});
const reader = stream.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

// Upload a scanner file
const formData = new FormData();
formData.append("file", new Blob([scanContent]), "scan.nessus");
const importResult = await fetch(`${BASE_URL}/api/scanner/import`, {
  method: "POST", body: formData,
}).then(r => r.json());
console.log(`Imported ${importResult.totalFindings} findings`);

Rate Limits

Endpoint	Limit	Window	Notes
POST /api/chat	30 requests	60 seconds	Per IP address
POST .../remediate	3 concurrent	-	Queued up to 15 seconds
POST .../script/stream	Separate pool	-	Does not block remediation
AI generation (free tier)	10 per day	24 hours	Upgrade to remove limit
Request body size	10 MB	-	All /api/* routes
Scanner upload	50 MB	-	POST /api/scanner/import

Error Handling

All errors return a JSON object with an error field. Some errors include a machine-readable code field for programmatic handling.

Error Response

{
  "error": "Free tier is limited to 10 AI generations per day.",
  "code": "upgrade_required"
}

Status	Code	Description
400	-	Invalid request parameters or body
401	AUTH_REQUIRED	Missing or invalid access token
403	upgrade_required	Feature requires paid license
403	pro_required	Feature requires Pro tier
404	-	Resource not found
413	-	Request body too large
429	-	Rate limit exceeded or queue full
500	-	Internal server error
503	-	AI engine not available

System

Health checks, AI engine status, database stats, and sync controls.

GET/health

Returns server health, uptime, and mode. No authentication required.

Response 200

{
  "status": "ok",
  "offline": false,
  "timestamp": "2026-03-15T12:00:00.000Z",
  "pid": 12345,
  "uptimeSec": 86400,
  "startedAt": "2026-03-14T12:00:00.000Z"
}

GET/api/status

Returns AI provider availability, loaded models, KEV catalog size.

Response 200

{
  "ollama": { "available": true, "model": "cve-advisor", "models": ["cve-advisor", "qwen3:32b"] },
  "ai": { "available": true, "engine": "CVEasy AI Engine", "ready": true },
  "offline": false,
  "kev": { "size": 1247 }
}

GET/api/stats

Returns database statistics: cached CVEs, enrichments, remediations.

GET/api/sync/status

Returns the status and timing of fresh sync, daily sync, and deep enrichment background jobs.

POST/api/sync/trigger

Starts a full daily CVE sync from NVD immediately. Returns 429 if a sync is already running.

CVE Intelligence

Search, lookup, and generate AI remediation for CVEs. Enriched with EPSS, CISA KEV, exploit intelligence, and TRIS scoring.

GET/api/cves/search?q={query}

Search by keyword, CVE ID, or GHSA ID. Searches local cache first; falls back to NVD/OSV.

Parameter	Type	Description
qrequired	string	CVE ID, keyword, or GHSA ID

Response 200

{
  "cves": [
    {
      "id": "CVE-2024-3094",
      "title": "XZ Utils Backdoor",
      "severity": "CRITICAL",
      "cvssScore": 10.0,
      "epssScore": 0.972,
      "epssPercentile": 0.998,
      "isKev": true,
      "hasPublicPoc": true,
      "ransomwareSignal": false,
      "wormable": false,
      "remedioScore": 98,
      "source": "nvd"
    }
  ],
  "source": "nvd-id"
}

GET/api/cves/recent

Returns the 20 most recently published CVEs from the local cache.

GET/api/cves/top-risk?limit={n}

Returns CVEs sorted by TRIS risk score (highest first). Default limit: 50, max: 200.

GET/api/cves/browse

Paginated browsing with severity filter and sort options.

Parameter	Type	Default
q	string	-
severity	ALL \| CRITICAL \| HIGH \| MEDIUM \| LOW	ALL
sort	published \| cvss \| remedio	published
offset	integer	0
limit	integer	50 (max 100)

GET/api/cves/{id}

Full CVE detail with description, CVSS, EPSS, KEV status, exploit signals, and cached remediation. Auto-fetches from NVD if not cached.

Response 200

{
  "id": "CVE-2024-3094",
  "title": "XZ Utils Backdoor",
  "description": "Malicious code was discovered in xz-utils...",
  "severity": "CRITICAL",
  "cvssScore": 10.0,
  "cvssVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
  "epssScore": 0.972,
  "epssPercentile": 0.998,
  "isKev": true,
  "kevDateAdded": "2024-03-30",
  "hasPublicPoc": true,
  "exploitReferenceCount": 14,
  "ransomwareSignal": false,
  "wormable": false,
  "attackerScore": 22.5,
  "remedioScore": 98,
  "affectedProducts": ["xz-utils 5.6.0", "xz-utils 5.6.1"],
  "remediation": "## Remediation Guide\n\n...",
  "remediationGeneratedAt": "2026-03-15T10:00:00Z",
  "source": "nvd"
}

POST/api/cves/{id}/remediate

Generates an AI remediation guide. Returns cached result unless force=1.

Parameter	Type	Description
mode	fast \| balanced \| quality	AI generation depth (default: fast)
force	0 \| 1	Force regeneration even if cached

Response 200

{
  "remediation": "## Remediation Guide for CVE-2024-3094\n\n### Impact\n...",
  "cached": false,
  "model": "cve-advisor"
}

POST/api/cves/{id}/remediate/stream

Streams the AI-generated remediation as a text stream. Tokens are sent as they are generated — ideal for real-time UI display.

POST/api/cves/{id}/script/stream

Streams AI-generated bash and PowerShell remediation scripts for the CVE.

GET/api/cves/{id}/pdf

Downloads a single-CVE PDF report with all enrichment data.

POST/api/config/enterprise-score/{cveId}

Computes the TrueRisk Intelligence Score (TRIS) using the 7-layer engine: intrinsic, threat, exposure, temporal, business, validation, intelligence.

Response 200

{
  "score": 87,
  "band": "ACT",
  "slaHours": 24,
  "layers": {
    "intrinsic": 28.5,
    "threat": 22.0,
    "exposure": 12.0,
    "temporal": 8.5,
    "business": 7.0,
    "validation": 5.0,
    "intelligence": 4.0
  },
  "reasoning": "This CVE requires immediate action. CISA KEV listing confirms..."
}

POST/api/cves/ingest

Manually ingest a CVE entry (internal advisories, custom vulnerability data).

Request Body

{
  "id": "CVE-2024-99999",
  "title": "Internal Web App SQL Injection",
  "description": "SQL injection in login form of internal HR portal",
  "severity": "HIGH",
  "cvssScore": 8.6,
  "affectedProducts": ["hr-portal v3.2.1"]
}

GET/api/cves/export

Export CVEs as CSV or JSON (up to 5,000 rows). Requires a paid license.

Parameter	Type	Default
format	csv \| json	csv
q	string	-
severity	string	ALL
ids	string	Comma-separated CVE IDs

Assets

Import vulnerability scans, view hosts, and get AI-powered environment risk analysis.

POST/api/assets/import

Upload a vulnerability scan file (.nessus, .xml, .csv, .json) to import asset and finding data.

cURL Example

curl -X POST http://localhost:3001/api/assets/import \
  -F "file=@nessus-scan.nessus"

GET/api/assets/imports

Returns all scan import records with file info and finding counts.

GET/api/assets/imports/{id}/risk-hosts

Returns host inventory enriched with CVE risk signals (KEV, EPSS, ransomware, wormability). Each host includes a composite risk score and top CVEs.

POST/api/assets/imports/{id}/analyze

Streams an AI-generated executive summary of environment security exposure. Optionally pass publicFacingHosts to increase risk priority for internet-exposed assets.

GET/api/assets/stats

Aggregate statistics about imported assets and findings.

Triage

Manage the vulnerability triage queue. Assign, prioritize, track SLAs, and fire webhooks on state changes.

GET/api/triage?state={state}&limit={n}

Returns the triage queue. Each item includes its enriched CVE data.

Parameter	Type	Description
state	pending \| in_review \| accepted \| in_progress \| resolved \| dismissed	Filter by state (optional)
limit	integer	Max results (default 200, max 500)

POST/api/triage

Add a CVE to the triage queue. Returns existing item if already triaged.

Request Body

{
  "cveId": "CVE-2024-3094",
  "assignee": "security-team",
  "notes": "Critical — needs immediate attention"
}

POST/api/triage/batch

Bulk add multiple CVEs to the triage queue.

Request Body

{ "cveIds": ["CVE-2024-3094", "CVE-2024-21762", "CVE-2024-1709"] }

POST/api/triage/{id}

Update triage item state, assignee, due date, or notes. Fires a webhook on state change.

Request Body

{
  "state": "in_progress",
  "assignee": "alice@company.com",
  "dueDate": "2026-03-20T00:00:00Z",
  "notes": "Patch deployed to staging, production pending change window"
}

GET/api/triage/stats

Returns counts of triage items by state.

Scanner Import

Ingest vulnerability scanner results from Nessus, Qualys, Nuclei, Burp Suite, OWASP ZAP, and Trivy. Auto-detects format.

POST/api/scanner/import

Upload scanner output (multipart/form-data or raw text). Max 50MB. Auto-detects format or use format hint.

Response 200

{
  "importId": 1,
  "filename": "scan-2024-Q1.nessus",
  "format": "nessus",
  "totalFindings": 247,
  "severity": { "critical": 12, "high": 45, "medium": 98, "low": 67, "info": 25 },
  "uniqueCVEs": 83,
  "cves": ["CVE-2024-3094", "CVE-2024-21762", "..."]
}

GET/api/scanner/imports

List all scanner imports with finding counts and severity breakdown.

GET/api/scanner/imports/{id}

Returns import details with paginated findings. Filter by severity or triage status.

POST/api/scanner/imports/{id}/triage

Creates triage queue items from all untriaged findings with CVEs in this import.

GET/api/scanner/formats

Lists all supported scanner formats with file extensions.

Reports

Generate executive summaries, technical findings, remediation roadmaps, attack simulation reports, and board narratives. HTML and PDF formats.

GET/api/reports/types

Lists available report types: executive, findings, roadmap, attack-simulation, patch-compliance, board-narrative.

POST/api/reports/generate

Generates a full HTML report. Requires a paid license.

Request Body

{
  "type": "executive",
  "filters": { "companyName": "Acme Corp" }
}

POST/api/reports/generate/pdf

Generates a PDF report. Supports executive, findings, and roadmap types. Returns binary PDF.

cURL Example

curl -X POST http://localhost:3001/api/reports/generate/pdf \
  -H "Content-Type: application/json" \
  -d '{"type": "executive"}' \
  -o executive-report.pdf

Metrics / SLA Dashboard

KPIs, burndown charts, asset heatmaps, compliance reports, and SLA tracking.

GET/api/metrics/summary

Quick KPI snapshot: total CVEs, severity distribution, SLA compliance rate, MTTR, and burndown velocity.

Response 200

{
  "timestamp": "2026-03-15T12:00:00Z",
  "metrics": {
    "totalCVEs": 4521,
    "criticalCount": 127,
    "highCount": 892,
    "mediumCount": 2104,
    "lowCount": 1398,
    "slaComplianceRate": 0.94,
    "burndownVelocity": 12.3,
    "avgTimeToRemediate": 6
  },
  "distribution": { "CRITICAL PRIORITY": 127, "HIGH PRIORITY": 892, "..." : "..." }
}

GET/api/metrics/dashboard

Full executive dashboard with KPIs, top risks (real CVE IDs), severity trends, and SLA metrics.

GET/api/metrics/burndown

30-day burndown chart data: daily cumulative CVEs by severity and cumulative resolved count.

GET/api/metrics/heatmap

Top 50 assets by risk score with critical/high vulnerability counts and recommended actions.

GET/api/metrics/compliance/{framework}

Compliance assessment for PCI-DSS, SOC2, HIPAA, NIST, or other frameworks.

AI Chat

Multi-turn AI security assistant. Supports optional CVE context and model selection.

POST/api/chat

Send a conversation to the AI assistant. Returns a streaming text response. Rate limited to 30 req/min per IP. Max 3 concurrent streams.

Request Body

{
  "messages": [
    { "role": "user", "content": "How should I remediate CVE-2024-3094?" }
  ],
  "mode": "balanced",
  "cveId": "CVE-2024-3094"
}

cURL Example (streaming)

curl -N -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What are the top 5 CVEs I should patch this week?"}], "mode": "fast"}'

Configuration

Manage application settings, AI provider, model routing, and deployment mode.

GET/api/config/settings

Returns current settings: company profile, AI provider, model routing, compliance frameworks.

POST/api/config/settings

Update settings. Only provide fields you want to change.

Request Body (partial update)

{
  "companyName": "Acme Corp",
  "industry": "Financial Services",
  "complianceFrameworks": ["PCI-DSS", "SOC2"],
  "aiProvider": "ollama",
  "aiModel": "qwen3:32b"
}

GET/api/config/provider-status

Returns the current AI provider's availability and configured model.

Webhooks

Configure outbound webhooks for Slack, Teams, Jira, or generic HTTPS endpoints. Fires on triage state changes and new critical CVEs.

GET/api/webhooks

List all configured webhooks.

POST/api/webhooks

Create a new webhook. URL must use HTTPS (except localhost for dev).

Request Body

{
  "name": "Slack Security Alerts",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "type": "slack",
  "events": ["triage.state_change", "cve.new_critical"],
  "enabled": true
}

POST/api/webhooks/{id}/test

Sends a test payload to verify the webhook endpoint is reachable.

Bulk Export

Export data as CSV or JSON for external reporting, audits, or data warehouse ingestion.

GET/api/export/cves?format={csv|json}

Export all CVEs (up to 5,000). Supports optional keyword filter with q parameter.

GET/api/export/assets

Export asset inventory.

GET/api/export/triage

Export triage queue with status, priority, assignee, and timestamps.

OpenAPI Specification

The full OpenAPI 3.0 spec is available from your running instance. Use it with Swagger UI, Postman, or any OpenAPI-compatible tool.

GET /api/docs (JSON) Open Swagger UI