Knowledge Base / API Reference

API Reference

The Donjon REST API runs on https://localhost:8443 and provides full programmatic access to all platform capabilities. All endpoints return JSON unless otherwise noted.

Base URL

https://localhost:8443/api/v1

Authentication

API requests require an API key passed via the X-API-Key header. The dashboard (GET /) does not require authentication.

# Include the API key in every request
curl -H "X-API-Key: your-api-key-here" \
     https://localhost:8443/api/v1/stats

Unauthenticated requests receive a 401 Unauthorized response:

{
  "error": true,
  "message": "Authentication required"
}

Endpoints Overview

All endpoints are prefixed with /api/v1. The API uses standard HTTP methods and returns JSON responses.

Health and Stats

GET /api/v1/health Health check

GET /api/v1/stats Platform statistics and overview

GET /api/v1/scanners List available scanners for current tier

GET /api/v1/network/local Local network information

Example: GET /api/v1/stats

// Response
{
  "total_scans": 42,
  "total_findings": 187,
  "findings_by_severity": {
    "CRITICAL": 3,
    "HIGH": 15,
    "MEDIUM": 48,
    "LOW": 72,
    "INFO": 49
  },
  "tier": "community",
  "uptime_seconds": 3600
}

Scans

POST /api/v1/scans Start a new scan

GET /api/v1/scans List all scan sessions

GET /api/v1/scans/{session_id} Get scan session details

GET /api/v1/scans/{session_id}/findings Get findings for a session

GET /api/v1/scans/{session_id}/export Export scan results

Example: Start a Scan

// POST /api/v1/scans
{
  "scanner": "network",
  "targets": ["192.168.1.0/24"],
  "scan_type": "quick"
}

// Response
{
  "session_id": "sess-a1b2c3d4",
  "scanner": "network",
  "status": "running",
  "started_at": "2026-02-15T10:30:00Z"
}

Example: Export Scan

// GET /api/v1/scans/sess-a1b2c3d4/export?format=csv
// Returns CSV file download

// Query parameters:
//   format: csv | json | html | pdf | sarif | xml
//   (html, pdf, sarif, xml require Pro tier)

Findings

GET /api/v1/findings List all findings

GET /api/v1/findings/{id} Get finding details

Assets

GET /api/v1/assets List all assets

POST /api/v1/assets Create an asset

GET /api/v1/assets/{id} Get asset details

PUT /api/v1/assets/{id} Update an asset

Example: Create Asset

// POST /api/v1/assets
{
  "hostname": "web-server-01",
  "ip_address": "10.0.1.50",
  "asset_type": "server",
  "business_unit": "engineering",
  "criticality": "high"
}

Remediation

GET /api/v1/remediation List remediation items

POST /api/v1/remediation Create remediation item

PUT /api/v1/remediation/{id} Update remediation item

GET /api/v1/remediation/metrics Remediation metrics (MTTR, etc.)

Risks

GET /api/v1/risks List risks in the risk register

POST /api/v1/risks Create a risk entry

GET /api/v1/risks/posture Overall risk posture summary

GET /api/v1/risks/matrix Risk heatmap matrix

Risk Exceptions

GET /api/v1/exceptions List risk exceptions

POST /api/v1/exceptions Create a risk exception

PUT /api/v1/exceptions/{id}/approve Approve a risk exception

AI Analysis

GET /api/v1/ai/status AI engine status and quota

GET /api/v1/ai/config Get AI configuration

POST /api/v1/ai/config Update AI configuration

POST /api/v1/ai/test Test AI provider connection

POST /api/v1/ai/analyze Analyze a specific finding

POST /api/v1/ai/triage Triage a list of findings

POST /api/v1/ai/remediate Generate remediation guidance

POST /api/v1/ai/summarize/{session_id} Generate scan summary (Pro+)

POST /api/v1/ai/query Free-form AI query

Example: Analyze Finding

// POST /api/v1/ai/analyze
{
  "finding": {
    "title": "SQL Injection in Login Form",
    "severity": "CRITICAL",
    "cvss_score": 9.8,
    "epss_score": 0.92,
    "kev_status": "true",
    "affected_asset": "10.0.0.5",
    "remediation": "Use parameterized queries."
  }
}

// Response
{
  "analysis": "This is a critical SQL injection vulnerability...",
  "risk_level": "CRITICAL",
  "recommendations": [ ... ],
  "ai_generated": true,
  "disclaimer": "AI-Generated - Verify Before Acting"
}

Reports and Compliance

GET /api/v1/reports/executive Executive summary report

GET /api/v1/reports/compliance/{framework} Compliance report for a framework

POST /api/v1/export Bulk export data

Schedules (Pro+)

GET /api/v1/schedules List scheduled scans

POST /api/v1/schedules Create a scheduled scan

GET /api/v1/schedules/{id} Get schedule details

PUT /api/v1/schedules/{id} Update a schedule

DELETE /api/v1/schedules/{id} Delete a schedule

GET /api/v1/schedules/{id}/history Schedule execution history

Notifications

GET /api/v1/notifications/channels List notification channels

POST /api/v1/notifications/channels Create a notification channel

PUT /api/v1/notifications/channels/{id} Update a notification channel

DELETE /api/v1/notifications/channels/{id} Delete a notification channel

POST /api/v1/notifications/test Send a test notification

GET /api/v1/notifications/history Notification delivery history

GET /api/v1/notifications/stats Notification statistics

Example: Create Webhook Channel

// POST /api/v1/notifications/channels
{
  "name": "security-alerts",
  "channel_type": "webhook",
  "config": {
    "url": "https://hooks.example.com/security"
  }
}

// Response
{
  "channel_id": "ch-x1y2z3",
  "name": "security-alerts",
  "status": "active"
}

Additional Endpoints

Discovery

POST /api/v1/discovery/scan Run a network discovery scan

GET /api/v1/discovery/hosts List discovered hosts

Agents

POST /api/v1/agents/checkin Agent check-in

GET /api/v1/agents List registered agents

Audit

GET /api/v1/audit View audit log

Maintenance

POST /api/v1/maintenance/purge-scans Purge old scan data

POST /api/v1/maintenance/purge-notifications Purge notification history

POST /api/v1/maintenance/purge-audit Purge audit log entries

License

GET /api/v1/license Get license info and current tier

POST /api/v1/license/activate Activate a new license

Example: License Info

// GET /api/v1/license
{
  "tier": "community",
  "organization": "",
  "expires": "",
  "license_id": "",
  "format_version": 0,
  "valid": true,
  "limits": {
    "scanners": ["network", "vulnerability", "web", "ssl", "windows", "linux", "compliance"],
    "scan_depths": ["quick", "standard"],
    "max_targets_per_scan": 16,
    "export_formats": ["csv", "json"],
    "ai_analysis": false,
    "max_users": 1,
    "api_rate_limit": 100
  }
}

Error Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Feature not available for current tier
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Server-side error

Tier Enforcement Errors

When a feature is not available for the current license tier, the API returns 403 Forbidden with an upgrade message:

{
  "error": true,
  "message": "Deep scans are a Pro feature. Community includes quick and standard depth. Upgrade to unlock deep scanning.",
  "tier": "community",
  "required_tier": "pro"
}

Rate Limiting

Tier	Requests / Hour
Community	100
Pro	10,000
Enterprise	Unlimited
Managed	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1739612400