API Reference

Run automated scans, retrieve results, and integrate VibeQA into your CI/CD pipeline.

Overview

The VibeQA API lets you trigger scans, retrieve results, and monitor usage programmatically. All requests use HTTPS and return JSON responses.

Common use cases include running a scan on every pull request, checking scan results in post-deploy scripts, and surfacing quality scores in dashboards.

Base URL

https://vibeqa.io/api

All endpoints below are relative to this base URL. For local development, use http://localhost:3847/api.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Authorization: Bearer vqa_YOUR_API_KEY_HERE

You can generate an API key from Settings → API Keys. Keep your keys secret — treat them like passwords. If a key is compromised, revoke it immediately and generate a new one.

Example request

curl -X POST https://vibeqa.io/api/scan \
  -H "Authorization: Bearer vqa_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com"}'

Error Handling

VibeQA uses standard HTTP status codes. Error responses include a JSON body with an error field describing what went wrong.

// Example error response
{
  "error": "Daily scan limit reached. Upgrade to Pro for 100 scans/day.",
  "upgrade": true,
  "suggestedPlan": "pro"
}

Scans

curl -X POST https://vibeqa.io/api/scan \
  -H "Authorization: Bearer vqa_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/checkout", "ownership_confirmed": true}'

{
  "scanId": "scan_abc123xyz",
  "status": "pending",
  "url": "https://yoursite.com/checkout",
  "createdAt": "2026-03-04T10:00:00.000Z"
}

{
  "scans": [
    {
      "id": "scan_abc123xyz",
      "url": "https://yoursite.com",
      "status": "completed",
      "createdAt": "2026-03-04T10:00:00.000Z",
      "completedAt": "2026-03-04T10:00:18.000Z",
      "summary": {
        "critical": 0,
        "warnings": 3,
        "info": 12,
        "loadTime": "1.4s",
        "score": 87
      }
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Scan Results

{
  "id": "scan_abc123xyz",
  "url": "https://yoursite.com",
  "status": "completed",
  "createdAt": "2026-03-04T10:00:00.000Z",
  "completedAt": "2026-03-04T10:00:18.000Z",
  "summary": {
    "critical": 0,
    "warnings": 3,
    "info": 12,
    "loadTime": "1.4s",
    "score": 87
  },
  "issues": [
    {
      "type": "warning",
      "category": "performance",
      "message": "Image missing explicit width/height",
      "element": "",
      "suggestion": "Add width and height attributes to prevent layout shift"
    }
  ]
}

User & Usage

{
  "currentPlan": "pro",
  "planLabel": "Pro",
  "planPrice": "$49",
  "status": "active",
  "renewalDate": "2026-04-01T00:00:00.000Z",
  "limits": {
    "scansPerDay": 100,
    "scansPerMonth": 1000,
    "historyDays": 90,
    "apiRequests": 1000
  },
  "usage": {
    "scansToday": 3,
    "scansThisMonth": 47,
    "scansAllTime": 312
  }
}

CI/CD Integration Example

This GitHub Actions workflow triggers a VibeQA scan on every push to main and fails the build if critical issues are found.

# .github/workflows/vibeqa.yml
name: VibeQA Scan

on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Run VibeQA Scan
        run: |
          RESULT=$(curl -s -X POST https://vibeqa.io/api/scan \
            -H "Authorization: Bearer ${{ secrets.VIBEQA_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"url\": \"${{ vars.SITE_URL }}\"}")

          SCAN_ID=$(echo $RESULT | jq -r '.scanId')
          echo "Scan ID: $SCAN_ID"

          # Poll for completion (max 60 seconds)
          for i in $(seq 1 12); do
            sleep 5
            STATUS=$(curl -s https://vibeqa.io/api/scans/$SCAN_ID \
              -H "Authorization: Bearer ${{ secrets.VIBEQA_API_KEY }}")

            STATE=$(echo $STATUS | jq -r '.status')
            if [ "$STATE" = "completed" ]; then
              CRITICAL=$(echo $STATUS | jq '.summary.critical')
              echo "Scan complete. Critical issues: $CRITICAL"
              if [ "$CRITICAL" -gt "0" ]; then
                echo "❌ Build failed: $CRITICAL critical issues found"
                exit 1
              fi
              echo "✅ No critical issues found"
              exit 0
            fi
          done

          echo "⚠️ Scan timed out"
          exit 1

Store your API key as a GitHub Actions secret named VIBEQA_API_KEY.