API Documentation

Integrate Guardn into your CI/CD pipeline, IDE, or custom tooling.

Authentication

API requests use Bearer token authentication with API keys. Keys use the gn_ prefix and are scoped to a team.

Create an API key from your account settings or via the API. New accounts get a Personal team automatically.

curl -X POST https://guardn.io/api/auth/apikey \
  -H "Cookie: guardn-session=<session>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline"}'

The response includes fullKey -- save it, it is shown only once. Use it in the Authorization header:

Authorization: Bearer gn_a1b2c3d4...

Scan Endpoints

POST/api/scanBearer token

Scan a single file. Returns findings, score, and severity breakdown.

curl -X POST https://guardn.io/api/scan \
  -H "Authorization: Bearer gn_<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"code": "const key = \"sk-proj-abc123\";", "filename": "app.ts"}'

POST/api/scan/batchBearer token

Scan up to 100 files in one request. Returns per-file results and aggregate summary.

curl -X POST https://guardn.io/api/scan/batch \
  -H "Authorization: Bearer gn_<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"filename": "app.ts", "code": "const key = \"sk-proj-abc123\";"},
      {"filename": "db.ts", "code": "const q = \"SELECT * FROM users WHERE id=\" + id;"}
    ]
  }'

POST/api/scan/fixBearer token

Scan and auto-fix. Returns patched code with findings resolved. 279 rules have auto-fix support.

POST/api/scan/gradePublic

Public endpoint. Score code without authentication. Rate limited to 10 requests/minute per IP.

curl -X POST https://guardn.io/api/scan/grade \
  -H "Content-Type: application/json" \
  -d '{"code": "eval(userInput);", "filename": "app.js"}'

POST/api/scan/realtimeBearer token

Optimized for editor integration. Debounced scanning for real-time feedback.

Export & Compliance

GET/api/scan/exportBearer token

Export scan results as SARIF v2.1.0. Compatible with GitHub Code Scanning, VS Code SARIF Viewer.

curl https://guardn.io/api/scan/export?scanId=<id>&format=sarif \
  -H "Authorization: Bearer gn_<your-api-key>"

GET/api/scan/complianceBearer token

Compliance mapping. Returns OWASP Top 10, SOC 2, HIPAA, PCI DSS, and ISO 27001 control status.

GET/api/scan/historyBearer token

List past scans with scores, finding counts, and timestamps.

GET/api/scan/history/searchBearer token

Search scan history by filename, rule, or severity.

Rules & Status

GET/api/rules/listBearer token

List all 300 security rules with category, severity, and CWE mappings.

GET/api/statusBearer token

System status: version, rule count, active features, PQ attestation state.

GitHub Action

Scan PRs and pushes automatically. Two modes: local (bundled engine, zero config) and api (Guardn cloud, needs API key).

# .github/workflows/guardn.yml
name: Guardn Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: guardn/action@v1
        with:
          mode: local        # or "api" with api-token
          fail-on: critical  # none | low | medium | high | critical

The action posts a comment with findings summary, sets exit code on threshold breach, and optionally outputs SARIF for GitHub Code Scanning.

CLI

Standalone scanner for local use, pre-commit hooks, and CI pipelines. 300 rules, 279 auto-fix, 47KB package.

# Install
npm install -g @guardn/cli

# Scan a file
guardn scan --file src/app.ts

# JSON output for CI
guardn scan --file src/app.ts --json

# List all 300 rules
guardn rules

Rate Limits

Tier	Limit	Window
Scan endpoints	30 requests	1 minute
Grade (public)	10 requests	1 minute
Auth endpoints	10 requests	1 minute
General API	60 requests	1 minute

Need help? support@guardn.io