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. Anonymous API results are not AI-filtered.

The endpoint

Single POST endpoint, accepts JSON, returns JSON. Body limit is 4.5 MB per request (Vercel serverless request-body limit).

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

4.5 MB per request (Vercel serverless request-body limit)
Application code also rejects bodies over 10 MB, but Vercel serverless caps the request at 4.5 MB first. 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 scan with the full 223 rules, see pricing for paid plans, then use the CLI with npx xploitscan@latest auth login, or the GitHub Action with an API key.
Root ignore file
A root .xploitscanignore included in the upload is applied. Nested ignore files are skipped with a warning. Paths that use .. or a drive letter are rejected. Responses include suppressedCount (inline and ignoreFile) and warnings. An ignore file over 64 KB or 2,000 lines is skipped. A marker needs a rule ID.
Rate limits
Without a scan token from the XploitScan web app, every request to the JSON or ZIP upload endpoint counts toward a limit of 3 scans a day per IP address, including requests that send an Authorization: Bearer header. The daily limit resets at 00:00 UTC. Per-minute limits also apply: 5 uploads per minute per IP for the JSON endpoint and 3 per minute for the ZIP endpoint. With a scan token from the XploitScan web app, those caps are 30 per minute on the JSON endpoint and 15 per minute on the ZIP endpoint. An Authorization: Bearer header does not raise them. A per-minute block returns HTTP 429 with a Retry-After header and standard RateLimit-* / X-RateLimit-* headers so clients can self-throttle. A daily-limit block returns HTTP 429 with resetsAt in the response body. If the daily limit can't be checked, the request returns HTTP 503 and no scan runs.
For CI, use the GitHub Action or the CLI with npx xploitscan@latest auth login. Both scan on your own machine or CI runner, so they don't count toward these API limits.

Need help? Run into something not covered above?

Email admin@xploitscan.com