# 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