API & CI

Last updated 30 October 2026

Studio plans include API keys. Create one in your dashboard, then call the scan endpoint from any pipeline. The response includes a pass flag so you can gate deploys.

Authentication

Send your key as a Bearer token. Keys are shown once at creation and stored hashed.

Authorization: Bearer vg_live_…

POST /api/v1/scan

Scan a live site or a GitHub repository. Optional fail_on is "critical", "high" or a minimum score (number).

curl -X POST https://vigilsec.app/api/v1/scan \
  -H "Authorization: Bearer $VIGIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com", "fail_on": "critical" }'

# repository (public), or add "token" for a private repo
  -d '{ "repo": "you/your-app", "fail_on": 70 }'

Response (abridged):

{
  "id": "scn_…", "target": "your-app.com", "score": 82, "grade": "A", "pass": true,
  "summary": { "critical": 0, "high": 1, "medium": 3, "low": 2, "passed": 44, "total": 6 },
  "diff": { "scoreDelta": +6, "newIssues": [], "fixedIssues": [{ "title": "No DMARC record" }] },
  "reportUrl": "https://vigilsec.app/r/scn_…",
  "categories": [ { "id": "security", "score": 90, "issues": [ { "severity": "high", "title": "…", "fix": "…", "prompt": "…" } ] } ]
}

GitHub Actions

Fail the deploy when a critical issue appears on the live site after each production release:

name: Vigil security gate
on:
  deployment_status:
jobs:
  vigil:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Scan production
        run: |
          RESULT=$(curl -s -X POST https://vigilsec.app/api/v1/scan \
            -H "Authorization: Bearer ${{ secrets.VIGIL_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url":"${{ github.event.deployment_status.target_url }}","fail_on":"critical"}')
          echo "$RESULT" | jq '{score, grade, pass, reportUrl}'
          [ "$(echo "$RESULT" | jq -r .pass)" = "true" ] || { echo "::error::Vigil found critical issues"; exit 1; }

Or scan the repository itself on every pull request:

on: [pull_request]
jobs:
  vigil-code:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -s -X POST https://vigilsec.app/api/v1/scan \
            -H "Authorization: Bearer ${{ secrets.VIGIL_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"repo":"${{ github.repository }}","token":"${{ secrets.GITHUB_TOKEN }}","fail_on":"high"}' \
          | jq -e '.pass == true'

Score badge

Make a report public from the Share card, then embed its badge. It always shows that report's score, so re-scan and re-share to update it.

[![Vigil score](https://vigilsec.app/badge/scn_….svg)](https://vigilsec.app/r/scn_…)

Limits