Docs — BugZeroAI

Getting Started

Quick Start

Get your first scan running in 3 steps. No installation required.

Step 1: Get your API key

# Your API key looks like this:
BUGZERO_API_KEY="bz_live_a1b2c3d4e5f6..."

Step 2: Start a scan

Point BugZeroAI at any HTTPS URL. The platform automatically detects your tech stack and selects the right modules.

curl -X POST https://api.bugzero.ai/scan \
  -H "Authorization: Bearer $BUGZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.your-app.com"
  }'

# Response:
{
  "scanId": "scan_7x8y9z",
  "status": "running",
  "modulesActivated": 24,
  "estimatedMinutes": 14
}

Step 3: Get results

Poll the scan status or use "wait": true to block until complete.

curl https://api.bugzero.ai/scan/scan_7x8y9z/report \
  -H "Authorization: Bearer $BUGZERO_API_KEY"

# Response:
{
  "verdict": "PASS",
  "readinessScore": 87,
  "issuesFound": 3,
  "critical": 0,
  "fixesGenerated": 2,
  "modules": { /* ... per-module results */ }
}

Authentication

All API requests require a Bearer token in the Authorization header. Keys are scoped to your organization.

# Include in every request:
-H "Authorization: Bearer bz_live_a1b2c3d4e5f6..."

# Test your key:
curl https://api.bugzero.ai/me \
  -H "Authorization: Bearer $BUGZERO_API_KEY"

Keys prefixed with bz_test_ hit the sandbox environment. Use bz_live_ for production scans.

Your First Scan

The simplest scan requires only a URL. BugZeroAI's App Intelligence phase detects your technology stack, authentication scheme, and available routes to automatically select the right modules.

For more control, you can specify modules explicitly:

{
  "url": "https://staging.your-app.com",
  "modules": ["pentest", "owasp", "brd", "performance"],
  "brdUrl": "https://docs.example.com/requirements.pdf",
  "auth": {
    "type": "bearer",
    "token": "your-staging-token"
  },
  "wait": true
}

API Reference

POST /scan

Create and start a new scan.

curl -X POST https://api.bugzero.ai/scan \
  -H "Authorization: Bearer $BUGZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com",
    "modules": ["pentest", "owasp", "brd", "ai-test-gen"],
    "brdUrl": "https://docs.example.com/brd.pdf",
    "auth": { "type": "bearer", "token": "staging-jwt" },
    "wait": false,
    "webhookUrl": "https://hooks.slack.com/your-webhook"
  }'

# Response 201:
{
  "scanId": "scan_a1b2c3d4",
  "status": "running",
  "modulesActivated": 4,
  "estimatedMinutes": 8,
  "createdAt": "2026-04-16T10:30:00Z"
}

Parameters:

url required Target URL to scan
modules Array of module IDs (omit for auto-select)
brdUrl URL to BRD document (PDF or text)
auth Authentication config for the target
wait Block until scan completes (default: false)
webhookUrl URL to POST results when scan completes

GET /scan/:id

Check the status of a running or completed scan.

curl https://api.bugzero.ai/scan/scan_a1b2c3d4 \
  -H "Authorization: Bearer $BUGZERO_API_KEY"

# Response:
{
  "scanId": "scan_a1b2c3d4",
  "status": "completed",
  "verdict": "PASS",
  "readinessScore": 87,
  "duration": "12m 34s",
  "issuesFound": 3,
  "modulesCompleted": 24
}

GET /scans

List all scans for your organization, with optional filters.

curl "https://api.bugzero.ai/scans?status=completed&limit=10" \
  -H "Authorization: Bearer $BUGZERO_API_KEY"

# Response:
{
  "scans": [
    {
      "scanId": "scan_a1b2c3d4",
      "url": "https://staging.example.com",
      "verdict": "PASS",
      "createdAt": "2026-04-16T10:30:00Z"
    }
  ],
  "total": 47,
  "page": 1
}

GET /scan/:id/report

Retrieve the full scan report with per-module results, issues, and generated fixes.

curl https://api.bugzero.ai/scan/scan_a1b2c3d4/report \
  -H "Authorization: Bearer $BUGZERO_API_KEY"

# Response (abbreviated):
{
  "verdict": "PASS",
  "readinessScore": 87,
  "issues": [
    {
      "id": "issue_x1y2",
      "module": "pentest",
      "severity": "medium",
      "title": "Reflected XSS in search parameter",
      "rootCause": {
        "explanation": "Input not sanitized before DOM insertion",
        "fix": { "prUrl": "https://github.com/org/repo/pull/42" }
      }
    }
  ]
}

Integrations

MCP Server

Use BugZeroAI directly from Claude Code, Cursor, or any MCP-compatible client. The MCP server exposes scan tools as callable functions.

// Add to .mcp.json or Claude Code settings:
{
  "mcpServers": {
    "bugzero": {
      "command": "npx",
      "args": ["bugzero-mcp-server"],
      "env": {
        "BUGZERO_API_KEY": "bz_live_your_key"
      }
    }
  }
}

Available MCP tools:

bugzero_scan Start a new scan

bugzero_status Check scan status

bugzero_report Get full scan report

bugzero_fix Trigger fix generation for an issue

GitHub Actions

Add BugZeroAI to your CI pipeline with a single workflow step.

name: QA Gate
on:
  pull_request:
    branches: [main]

jobs:
  bugzero:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to staging
        run: npm run deploy:staging

      - name: Run BugZeroAI Scan
        id: scan
        run: |
          RESULT=$(curl -s -X POST https://api.bugzero.ai/scan \
            -H "Authorization: Bearer ${{ secrets.BUGZERO_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url":"${{ vars.STAGING_URL }}","wait":true}')
          echo "verdict=$(echo $RESULT | jq -r .verdict)" >> $GITHUB_OUTPUT

      - name: Gate check
        if: steps.scan.outputs.verdict != 'PASS'
        run: |
          echo "BugZeroAI verdict: HOLD — blocking merge"
          exit 1

Webhooks

Receive scan results via HTTP POST to your endpoint. Include webhookUrl in your scan request.

# Payload sent to your webhook:
{
  "event": "scan.completed",
  "scanId": "scan_a1b2c3d4",
  "verdict": "PASS",
  "readinessScore": 87,
  "issuesFound": 3,
  "reportUrl": "https://app.bugzero.ai/scans/scan_a1b2c3d4"
}

Verify webhook authenticity using the X-BugZero-Signature header (HMAC-SHA256 of the payload body with your webhook secret).