REST API v1

API Documentation

Integrate ScanVibe security scanning into your CI/CD pipeline. Catch vulnerabilities before they reach production.

Overview

The ScanVibe API lets you programmatically scan any URL for security vulnerabilities. Designed for CI/CD integration, it returns a structured security report with scores, grades, and per-category results.

Base URL

https://scanvibe.dev/api/v1

All requests and responses use JSON. The API follows REST conventions.

Authentication

All API requests require a Bearer token. Generate your API token from the ScanVibe dashboard under Account > API Tokens.

API access requires a Business plan ($29/mo).

Include your token in the Authorization header:

Authorization: Bearer sv_live_your_token_here

Tokens are prefixed with sv_live_

Endpoints

POST/api/v1/scan

Submit a URL for security scanning. The scan runs synchronously and returns the full report.

curl

curl -X POST https://scanvibe.dev/api/v1/scan \
  -H "Authorization: Bearer sv_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.vercel.app",
    "threshold": 70
  }'

Request Body

Field	Type	Status	Description
`url`	`string`	required	The URL to scan. Must be a valid, publicly accessible HTTP(S) URL.
`threshold`	`number`	optional	Minimum acceptable score (0-100). If the scan score is below this value, the API returns HTTP 422 instead of 200. Perfect for CI/CD gates.
`multiPage`	`boolean`	default: false	Enable multi-page scanning. Crawls and scans linked pages (Business plan feature).

Response

Success (200)

Returns the full scan report when the score meets or exceeds the threshold (or no threshold is set).

{
  "id": "clx1abc2d0001abcdef",
  "url": "https://my-app.vercel.app",
  "score": 74,
  "grade": "C",
  "results": [
    {
      "category": "ssl",
      "score": 100,
      "severity": "pass",
      "summary": "Valid SSL certificate with strong configuration"
    },
    {
      "category": "headers",
      "score": 45,
      "severity": "high",
      "summary": "Missing Content-Security-Policy and X-Frame-Options"
    },
    {
      "category": "secrets",
      "score": 60,
      "severity": "medium",
      "summary": "Supabase anon key found in client bundle"
    }
  ]
}

Field	Description
`id`	Unique scan identifier
`url`	The scanned URL
`score`	Overall security score (0-100)
`grade`	Letter grade (A, B, C, D, or F)
`results`	Array of per-category results
`.category`	Security category (e.g., ssl, headers, secrets)
`.score`	Category score (0-100)
`.severity`	Severity level: critical, high, medium, low, info, or pass
`.summary`	Human-readable summary of findings

CI/CD Integration

Use the threshold parameter to fail your CI pipeline when the security score drops below an acceptable level. The API returns HTTP 422 when the score is below the threshold.

GitHub Actions Example

Add this step to your GitHub Actions workflow to gate deployments on a minimum security score:

# .github/workflows/security.yml
name: Security Scan

on:
  push:
    branches: [main]
  pull_request:

jobs:
  scanvibe:
    runs-on: ubuntu-latest
    steps:
      - name: ScanVibe Security Gate
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" \
            -X POST https://scanvibe.dev/api/v1/scan \
            -H "Authorization: Bearer ${{ secrets.SCANVIBE_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"url": "https://my-app.vercel.app", "threshold": 70}')

          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
          BODY=$(echo "$RESPONSE" | head -n -1)

          if [ "$HTTP_CODE" -eq 422 ]; then
            echo "Security score below threshold!"
            echo "$BODY" | jq .
            exit 1
          elif [ "$HTTP_CODE" -ne 200 ]; then
            echo "Scan failed with HTTP $HTTP_CODE"
            echo "$BODY"
            exit 1
          fi

          echo "Security scan passed!"
          echo "$BODY" | jq '{score: .score, grade: .grade}'

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with a message field.

Code	Meaning
`200`	Scan completed successfully. Score meets threshold.
`400`	Invalid request body or URL.
`401`	Missing or invalid API token.
`403`	Valid token but account is not on the Business plan.
`422`	Score below threshold. Body contains the full scan report so you can inspect failures.
`429`	Rate limited. Wait and retry.
`500`	Internal server error. Retry or contact support.

Rate Limits

Business plan API tokens are rate-limited to 60 requests per minute and 500 requests per day. Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Your per-minute request limit
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Seconds until the rate limit window resets

Ready to integrate?

Get your API token with a Business plan and start securing your CI/CD pipeline today.

View Pricing