API Documentation — XploitScan

Base URL

https://vibecheck-scanner-api.vercel.app

Authentication

Authenticated endpoints require a Bearer token obtained from Clerk. Include it in the Authorization header.

Authorization: Bearer YOUR_CLERK_TOKEN

Rate Limiting

Global: 100 requests per minute

Scan uploads: 10 requests per minute

Rate-limited responses return HTTP 429 with a Retry-After header.

Public API

These endpoints are available to all users. No authentication required.

GET/apiPublic

Health check. Returns API name, version, and status.

POST/api/scans/upload-jsonPublic10 requests/min

Submit files for security scanning. Returns findings, security grade (A+ to F), score, detected frameworks, OWASP/CWE mappings, and fix suggestions.

Body{ "files": [{ "path": "src/app.ts", "content": "..." }] }

GET/api/badge/:userIdPublic

Get a public SVG security badge showing the user's latest scan grade. Embed in your README or website. No authentication required.

Advanced Endpoints

These endpoints require authentication and are used by the dashboard. Most users won't need to call these directly.

GET/api/scansAuth required

List scan history for the authenticated user. Supports pagination.

Query params

limit (default 20), offset (default 0)

GET/api/scans/:idAuth required

Get full details for a specific scan, including all findings and metadata.

GET/api/users/meAuth required

Get the current authenticated user profile.

POST/api/billing/checkoutAuth required

Create a Stripe checkout session for upgrading to a paid plan.

GET/api/billing/portalAuth required

Get a Stripe customer portal URL for managing subscription and billing.

Example: Scan Files

Request

terminal

curl -X POST https://vibecheck-scanner-api.vercel.app/api/scans/upload-json \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "src/api/auth.ts",
        "content": "const password = \"admin123\";\napp.post(\"/login\", (req, res) => {\n  if (req.body.pw === password) res.json({ token: \"secret\" });\n});"
      }
    ]
  }'

Response

200 OK

{
  "findings": [
    {
      "id": "VC001-src/api/auth.ts:1",
      "rule": "VC001",
      "severity": "critical",
      "title": "Hardcoded API Key or Secret",
      "description": "Hardcoded password found in source code",
      "file": "src/api/auth.ts",
      "line": 1,
      "fix": "Use environment variables for sensitive values",
      "category": "Secrets",
      "owasp": "A02:2021",
      "cwe": "CWE-798"
    }
  ],
  "filesScanned": 1,
  "duration": 12,
  "grade": "D",
  "score": 35,
  "gradeSummary": "Significant security issues found.",
  "frameworks": ["express"],
  "totalRules": 96,
  "percentile": 20,
  "criticalCount": 1,
  "highCount": 0,
  "mediumCount": 0,
  "lowCount": 0
}