Developers

API reference

Queue cross-service vulnerability scans from your CI/CD pipeline. Authenticate with a workspace API key created in Settings → API keys.

Authentication

Send your key as a bearer token. Keys are workspace-scoped and shown once at creation.

Authorization: Bearer vg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Base URL: https://vulngraph.us

Example — scan on every push

Queue a scan from CI and poll for the result:

# Queue a scan
curl -X POST https://vulngraph.us/api/v1/scans \
  -H "Authorization: Bearer $VULNGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repository":"owner/repo"}'
# => {"id":"<scan-id>","status":"queued","status_url":"…"}

# Check status
curl https://vulngraph.us/api/v1/scans/<scan-id> \
  -H "Authorization: Bearer $VULNGRAPH_API_KEY"
# => {"status":"completed","findings":{"total":3,"by_severity":{"critical":1,"high":1}}}

GitHub Action

Drop VulnGraph into CI and fail the build on critical/high findings. Store your key as the secret VULNGRAPH_API_KEY:

name: VulnGraph
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/vulngraph-scan
        with:
          api-key: ${{ secrets.VULNGRAPH_API_KEY }}
          fail-on: high   # none | high | critical

Add sarif-file: vulngraph.sarif and a github/codeql-action/upload-sarif step to surface findings in the repo's Security → Code scanning tab (Team plan and up).

Rate limits

Scan creation is limited to 30 requests/minute per key; read endpoints to 60/minute. Exceeding a limit returns 429. Revoke a key any time in Settings.