Getting Started

Prerequisites

• A GovNu account on any tier (Starter, Pro, or Enterprise). View plans
• An API key generated from Settings > API Keys
• A Git repository you want to scan

All API requests use Bearer token authentication. Store your API key as an environment variable — never hard-code it in source files.

export GOVNU_API_KEY="gn_live_your_api_key_here"

curl https://api.govnu.dev/v1/scans \
  -H "Authorization: Bearer $GOVNU_API_KEY"

Send a POST request to /v1/scans with your repository URL and branch. The API returns a scan object with a status of pending.

curl -X POST https://api.govnu.dev/v1/scans \
  -H "Authorization: Bearer $GOVNU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "https://github.com/your-org/your-repo",
    "branch": "main"
  }'

Scans run asynchronously. Poll the scan endpoint until the status changes to completed or failed. Alternatively, register a webhook to receive a notification when the scan finishes.

# Poll until status is "completed" or "failed"
curl https://api.govnu.dev/v1/scans/scan_01HXA... \
  -H "Authorization: Bearer $GOVNU_API_KEY"

{
  "id": "scan_01HXA2B3C4",
  "status": "completed",
  "repository": "https://github.com/your-org/your-repo",
  "branch": "main",
  "violationCount": 3,
  "createdAt": "2026-04-05T10:30:00Z",
  "completedAt": "2026-04-05T10:30:42Z"
}

Fetch the violations found by the scan. Each violation includes the rule that triggered it, the file and line number, severity, and a human-readable message explaining what to fix.

curl https://api.govnu.dev/v1/scans/scan_01HXA.../violations \
  -H "Authorization: Bearer $GOVNU_API_KEY"

{
  "data": [
    {
      "id": "viol_01HXA...",
      "rule": "no-direct-sdk-import",
      "severity": "high",
      "message": "Direct Supabase client import in route handler. Use the adapter module instead.",
      "file": "src/app/api/users/route.ts",
      "line": 3
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 3
  }
}

Next Steps