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",
  "resume": false,
  "auth": {
    "login_url": "https://example.com/login",
    "credentials": {
      "username": "[email protected]",
      "password": "${TARGET_PASSWORD}",
      "totp_secret": "JBSWY3DPEHPK3PXP"
    }
  },
  "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", "SQLi"],
  "elapsed_seconds": 342
}

POST /api/scans/{id}/stop

POST /api/scans/{id}/pause

POST /api/scans/{id}/resume

Resumes scans that have recoverable state, including scans paused by the circuit breaker, interrupted connections, or manual pauses. If system concurrency limits are reached, the API returns HTTP 429 instead of starting unbounded resume work.

DELETE /api/scans/{id}

Deletes scan metadata and performs cleanup using the scan origin and lifecycle state to avoid removing unrelated reports.

The scan creation payload accepts an optional auth object. WEB normally builds this object from an uploaded YAML auth config.

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",
      "discovered_at": "2026-02-10T14:35:22Z"
    }
  ],
  "total": 12
}

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-3-flash-preview",
  "CODE_MODEL": "deepseek/deepseek-chat-v3-0324",
  "ANALYSIS_MODEL": "anthropic/claude-haiku-4.5",
  "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}/detailed-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. Sub-resources expose specific subsystems:

POST /api/scans/{id}/re-enrich

Re-runs PoC/evidence enrichment over an existing scan's findings without re-scanning.

Manage the active LLM provider/preset used by the CLI.

The integrated Model Lab (model-eval) benchmark compares OpenRouter models through the CLI API. It can run with its own OpenRouter key, independent of the scanner's active provider: the GET endpoints accept the key via an X-OpenRouter-Key header, and POST /api/model-eval accepts it as an api_key field in the request body. Without a supplied key, the active provider's key is used. The key always stays server-side.

POST /api/model-eval
Content-Type: application/json

{
  "models": ["google/gemini-3-flash-preview", "anthropic/claude-haiku-4.5"],
  "suite_id": "quick-v3",
  "runs": 2,
  "mutation_probe": false,
  "api_key": "sk-or-v1-..."
}

The benchmark scores candidates with a quality-dominant composite and reports a per-slot leaderboard (best model for the MUTATION / SKEPTICAL / ANALYSIS / REPORTING slots). Suites: quick-v3 (default) and advanced-v2. See Configuration for the MODELLAB_* scoring knobs.

GET /api/model-eval/test-key
X-OpenRouter-Key: sk-or-v1-...

/api/ws/model-eval/{job_id}

Streams per-model progress events while a benchmark runs, mirroring the REST job state.

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