The BugTraceAI-CLI exposes a REST API via FastAPI on port 8000. This API provides complete programmatic access to scan management, findings, reports, configuration, and metrics. The API follows the OpenAPI 3.1 specification.

http://localhost:8000

Interactive API documentation (Swagger UI) is available at:

http://localhost:8000/docs

POST /api/scans
Content-Type: application/json

{
  "target_url": "https://example.com",
  "scan_type": "full",
  "config": {
    "max_depth": 3,
    "max_urls": 500,
    "safe_mode": false
  }
}

Response (201 Created):

{
  "id": "scan_abc123",
  "status": "QUEUED",
  "target_url": "https://example.com",
  "origin": "web",
  "created_at": "2026-02-10T14:30:00Z"
}

The origin field indicates where the scan was launched from:

GET /api/scans

Returns all scans with their current status.

GET /api/scans/{id}/status

Response:

{
  "id": "scan_abc123",
  "status": "RUNNING",
  "phase": "exploitation",
  "progress": 65,
  "findings_count": 12,
  "active_agents": ["xss_specialist", "sqli_specialist"],
  "elapsed_seconds": 342
}

POST /api/scans/{id}/start

POST /api/scans/{id}/stop

POST /api/scans/{id}/pause

POST /api/scans/{id}/resume

GET /api/scans/{id}/findings

Response:

{
  "findings": [
    {
      "id": "finding_001",
      "type": "XSS",
      "subtype": "reflected",
      "severity": "HIGH",
      "confidence": 0.92,
      "url": "https://example.com/search?q=test",
      "parameter": "q",
      "payload": "<script>alert(1)</script>",
      "validation_status": "VALIDATED_CONFIRMED",
      "agent": "xss_specialist",
      "discovered_at": "2026-02-10T14:35:22Z"
    }
  ],
  "total": 12
}

GET /api/scans/{id}/findings/{finding_id}

GET /api/scans/{id}/report/{format}

Supported formats:

GET /api/scans/{id}/report-zip

Response: Binary ZIP file containing the complete report directory (final report, validated findings, specialist results, reconnaissance data, PoC enrichment, and all evidence files).

curl -o report.zip http://localhost:8000/api/scans/{id}/report-zip

GET /api/scans/{id}/files/{filename}

Returns individual files associated with a scan report (e.g., screenshots, evidence files).

GET /api/config

Response:

{
  "SAFE_MODE": false,
  "MAX_DEPTH": 3,
  "MAX_URLS": 500,
  "DEFAULT_MODEL": "google/gemini-2.5-flash",
  "CODE_MODEL": "anthropic/claude-sonnet-4",
  "ANALYSIS_MODEL": "google/gemini-2.5-pro",
  "HEADLESS_BROWSER": true,
  "EARLY_EXIT_ON_FINDING": false,
  "STOP_ON_CRITICAL": false,
  "REPORT_ONLY_VALIDATED": true,
  "OPENROUTER_API_KEY": "sk-or-...****"
}

Note: API keys are masked in GET responses for security.

PATCH /api/config
Content-Type: application/json

{
  "MAX_DEPTH": 5,
  "SAFE_MODE": true
}

See Configuration for details on all configuration options.

GET /api/scans/{id}/metrics

Returns performance metrics for a specific scan including depth reached, URLs processed, throughput, and per-agent statistics.

GET /api/metrics

Returns aggregate metrics across all scans.

In addition to REST, the CLI provides WebSocket endpoints for real-time event streaming:

See WebSocket Events for the full event protocol.

The CLI API supports API key authentication via the Authorization header:

Authorization: Bearer <api-key>

API key configuration is managed through the CLI configuration file or environment variables.

All error responses follow a consistent format:

{
  "detail": "Scan not found",
  "status_code": 404
}

The API does not impose rate limits by default. In production deployments, rate limiting should be configured at the reverse proxy level (e.g., Nginx).

The full OpenAPI 3.1 specification is auto-generated by FastAPI and available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• JSON Spec: http://localhost:8000/openapi.json

Parent: Architecture

See also: WebSocket Events | Configuration | BugTraceAI-CLI