Guide · 4 min

Call the API directly

POST a JSON payload of files to the public scan endpoint and get back grade, score, and findings. Usable from any CI system, custom build tool, or scripted workflow. No API key required for the public endpoint.

The endpoint

Single POST endpoint, accepts JSON, returns JSON. Body limit is 5MB.

endpoint

POST https://xploitscan-api.vercel.app/api/scans/upload-json

Send a single-file scan with curl

Quickest way to confirm the endpoint is reachable. The body is a JSON object with a files array; each file has a path and content.

bash

curl -X POST https://xploitscan-api.vercel.app/api/scans/upload-json \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "server.js",
        "content": "const API_KEY = \"sk_live_abc123\";"
      }
    ]
  }'

Read the response

You should get back a JSON object with the grade, severity counts, and a list of findings:

{
  "grade": "F",
  "score": 0,
  "filesScanned": 1,
  "criticalCount": 1,
  "highCount": 0,
  "mediumCount": 0,
  "lowCount": 0,
  "findings": [
    {
      "id": "f_001",
      "rule": "VC001",
      "severity": "critical",
      "title": "Hardcoded API Key",
      "description": "API key committed to source code",
      "file": "server.js",
      "line": 1,
      "fix": "Move to environment variable"
    }
  ]
}

Each finding includes rule, severity, title, description, file, line, and an optional fix string.

Wire it into a Node script

Drop this into your build pipeline. It scans a single file and exits non-zero on any critical finding.

javascript

// scan.js
import { readFileSync } from 'node:fs';

const file = process.argv[2];
const content = readFileSync(file, 'utf8');

const res = await fetch(
  'https://xploitscan-api.vercel.app/api/scans/upload-json',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ files: [{ path: file, content }] }),
  },
);

const data = await res.json();
console.log(`Grade: ${data.grade} (${data.score}/100)`);
console.log(`Findings: ${data.findings.length}`);
process.exit(data.criticalCount > 0 ? 1 : 0);

bash

node scan.js server.js

Limits and rules

5MB body limit
For larger projects, scan in batches or use the CLI which streams files.
Public endpoint = 30 free rules
The public endpoint runs the same 30-rule set as anonymous web scans. To unlock the full 206 rules, sign up and use the CLI with npx xploitscan auth login, or use the GitHub Action with your account.
Rate limits
Anonymous requests: 5 scan uploads per minute per IP (JSON endpoint) or 3/min for the ZIP endpoint. Authenticated requests (any Authorization: Bearer header present): 30 per minute. Blocked responses return HTTP 429 with a Retry-After header and standard RateLimit-* / X-RateLimit-* headers so clients can self-throttle.
For production CI use, prefer the GitHub Action or the CLI with npx xploitscan auth login — both authenticate and get the higher rate limit automatically.

Need help? Run into something not covered above?

Email admin@xploitscan.com