API Documentation

The HeaderGuard API lets you integrate security header scanning into your CI/CD pipeline, scripts, and dashboards. Pro API access requires an API key generated from your dashboard.

Base URL

https://headerguard.io/api/v1

Authentication

All Pro API endpoints require a Bearer token in the Authorization header. Generate your API key from the Dashboard.

terminal

curl -X POST https://headerguard.io/api/v1/scan \
  -H "Authorization: Bearer hg_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

POST /scan

Run a security header scan against a URL. Returns grade, score, and per-header results.

Request body

request.json

{
  "url": "https://example.com",
  "threshold": "B"          // Optional: grade threshold for pass/fail
}

Response (200 OK)

response.json

{
  "scan_id": "a1b2c3d4-...",
  "url": "https://example.com",
  "grade": "C",
  "score": 58,
  "passed": false,
  "threshold": "B",
  "scanned_at": "2026-02-18T12:00:00Z",
  "results_url": "https://headerguard.io/scan/a1b2c3d4-...",
  "headers": [
    {
      "name": "content-security-policy",
      "label": "Content-Security-Policy",
      "present": false,
      "value": null,
      "score": 0,
      "max_score": 30,
      "severity": "critical",
      "issues": ["Content-Security-Policy header is missing entirely"]
    }
  ]
}

GitHub Actions Integration

Add this workflow to your repository to fail builds when security headers drop below a threshold. Add your API key as a repository secret named HEADERGUARD_API_KEY.

.github/workflows/security-headers.yml

# .github/workflows/security-headers.yml
name: Security Headers Check

on:
  deployment_status:

jobs:
  check-headers:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Check Security Headers
        run: |
          RESPONSE=$(curl -s -X POST https://headerguard.io/api/v1/scan \
            -H "Authorization: Bearer ${{ secrets.HEADERGUARD_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url": "${{ github.event.deployment_status.environment_url }}", "threshold": "B"}')

          PASSED=$(echo $RESPONSE | jq -r '.passed')
          GRADE=$(echo $RESPONSE | jq -r '.grade')

          echo "Security Header Grade: $GRADE"

          if [ "$PASSED" != "true" ]; then
            echo "FAILED: Security header grade $GRADE is below threshold B"
            echo "Full results: $(echo $RESPONSE | jq -r '.results_url')"
            exit 1
          fi

          echo "PASSED: Security headers meet the required grade threshold"

Error Codes

400invalid_urlThe URL is malformed or targets a private IP range

401invalid_api_keyThe API key is invalid, revoked, or belongs to a free account

422unreachable_urlThe target URL could not be reached within the timeout

429rate_limit_exceededMonthly API quota (100 scans/month) has been exceeded

500internal_errorAn unexpected server error occurred