API Reference

Authentication

All API requests require a Bearer token. Standalone API keys are not yet issued. Run sigil login to complete a browser-based device authorization flow (POST /v1/auth/device/code, then POST /v1/auth/device/token); the CLI stores the resulting token at ~/.sigil/token.

sigil login

curl -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  https://api.sigilsec.ai/v1/scans

Base URL

https://api.sigilsec.ai/v1

Scan, threat, and policy endpoints are versioned under /v1; team endpoints are mounted at /team. Rate limits: 200 requests per 60 seconds per IP across the API, plus 30 requests per 60 seconds on POST /v1/scans. Each plan also has a monthly scan quota.

Endpoints

Submit scan results

Scanning runs locally in the CLI. The API stores the results. Body fields: target, target_type (directory, git, pip, npm), files_scanned, findings, and optional metadata.

# Equivalent to: sigil scan ./my-package --submit
curl -X POST https://api.sigilsec.ai/v1/scans \
  -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "./my-package",
    "target_type": "directory",
    "files_scanned": 0,
    "findings": []
  }'

Response

Field shape only; values in angle brackets are placeholders. Verdicts are LOW_RISK, MEDIUM_RISK, HIGH_RISK, or CRITICAL_RISK and report detection results, not a safety rating.

{
  "id": "<uuid>",
  "scan_id": "<uuid>",
  "target": "./my-package",
  "target_type": "directory",
  "files_scanned": 0,
  "findings": [],
  "risk_score": 0.0,
  "verdict": "LOW_RISK",
  "score": 0.0,
  "classification": "SUSPICIOUS",
  "threat_intel_hits": [],
  "created_at": "<ISO-8601 timestamp>",
  "disclaimer": "Automated static analysis result. Not a security certification. ..."
}

Error handling

Errors return a JSON body with a detail field. Validation errors (422) add an errors array; plan-gate errors (403) add required_plan, current_plan, and upgrade_url.

{
  "detail": "Rate limit exceeded. Max 200 requests per 60s."
}

{
  "detail": "Validation error",
  "errors": [{ "loc": ["body", "target"], "msg": "Field required", "type": "missing" }]
}