API Reference

CodeShield API v1

A single REST endpoint to scan code for vulnerabilities. Designed for CI/CD pipelines, editors, and security tooling.

Base URL

https://codeshield.sh/api/v1

Authentication

All requests require a bearer token. Generate one at /settings.

Authorization: Bearer cs_live_XXXXXXXXXXXX

Rate limits & quotas

60 requests / minute per IP.
Free: 10 scans / month · 100 files / scan.
Team: unlimited scans · 100 files / scan.
Business: unlimited scans · 200 files / scan.
Enterprise: unlimited · 500 files / scan.

Quota resets on the 1st of each month. When exceeded we return HTTP 429.

POST `/scan`

Scan either a code snippet or a public GitHub repo.

Scan a snippet

curl -X POST https://codeshield.sh/api/v1/scan \
  -H "Authorization: Bearer cs_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"code": "eval(req.body.payload)", "language": "js"}'

Scan a GitHub repo

curl -X POST https://codeshield.sh/api/v1/scan \
  -H "Authorization: Bearer cs_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"repo": "https://github.com/expressjs/express"}'

Response 200

{
  "success": true,
  "scan": {
    "filesScanned": 42,
    "vulnerabilities": [
      {
        "file": "src/auth.ts",
        "line": 128,
        "severity": "critical",
        "type": "code-injection",
        "cwe": "CWE-94",
        "message": "Use of eval() with user input"
      }
    ],
    "summary": { "critical": 1, "high": 0, "medium": 2, "low": 0, "total": 3 },
    "scannedAt": "2026-04-13T13:50:01.234Z"
  },
  "usage": { "plan": "growth", "scansRemaining": 849 }
}

Error responses

Status	Error code	Meaning
400	invalid_input	Missing or malformed fields.
401	missing_api_key	No Authorization header.
401	invalid_api_key	Key unknown or revoked.
403	private_repo	Use the dashboard for private repos.
404	repo_not_found	Repo missing or private.
429	rate_limit	IP rate limit hit.
429	quota_exceeded	Monthly scans exhausted.

SDK examples

Node.js

const res = await fetch("https://codeshield.sh/api/v1/scan", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESHIELD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ repo: "https://github.com/owner/repo" }),
});
const { scan } = await res.json();
if (scan.summary.critical > 0) process.exit(1);

Python

import os, requests
r = requests.post("https://codeshield.sh/api/v1/scan",
  headers={"Authorization": f"Bearer {os.environ['CODESHIELD_API_KEY']}"},
  json={"repo": "https://github.com/owner/repo"})
r.raise_for_status()
summary = r.json()["scan"]["summary"]
exit(1 if summary["critical"] else 0)

Webhooks

Auto-scan on every push or pull request — see the GitHub Action guide.