Reference

API Reference

The Sigil cloud API powers the web dashboard and CI/CD integrations. Available on Pro and Team plans.

Authentication

All API requests require a Bearer token. Generate an API key from your dashboard settings.

bash

curl -H "Authorization: Bearer sk_live_..." \
  https://api.sigilsec.ai/v1/scans

Keep your API key secret

Never commit API keys to version control or expose them in client-side code. Use environment variables in CI/CD pipelines.

Base URL

https://api.sigilsec.ai/v1

All endpoints are versioned under /v1. Rate limits: 100 requests/minute (Pro), 500 requests/minute (Team).

Endpoints

POST/v1/scansPro, Team

Submit a new scan. Returns a scan ID for polling results.

GET/v1/scans/:idPro, Team

Get scan result by ID. Includes full verdict, score, and per-phase findings.

GET/v1/scansPro, Team

List scan history with pagination and filtering. Supports date range, verdict, and target filters.

GET/v1/threatsPro, Team

Query the threat intelligence database. Returns known malicious packages and patterns.

POST/v1/policies/evaluateTeam

Evaluate a scan result against a custom policy. Returns pass/fail and policy violations.

GET/v1/team/membersTeam

List team members, roles, and scan activity.

Submit a scan

bash

curl -X POST https://api.sigilsec.ai/v1/scans \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target": "npm:express@4.18.2",
    "policy": "default"
  }'

Response

json

{
  "id": "scan_01abc...",
  "status": "completed",
  "target": "npm:express@4.18.2",
  "score": 0,
  "verdict": "clean",
  "phases": {
    "install_hooks": { "score": 0, "findings": [] },
    "code_patterns": { "score": 0, "findings": [] },
    "network_exfil": { "score": 0, "findings": [] },
    "credentials":   { "score": 0, "findings": [] },
    "obfuscation":   { "score": 0, "findings": [] },
    "provenance":    { "score": 0, "findings": [] }
  },
  "duration_ms": 2140,
  "created_at": "2026-02-19T10:30:00Z"
}

Error handling

All errors return a consistent JSON structure with an error code and message.

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "status": 429
  }
}

Status	Description
401	Invalid or missing API key
403	Endpoint not available on your plan
404	Resource not found
422	Invalid request body or parameters
429	Rate limit exceeded

SDK libraries

Official TypeScript and Python SDK libraries are in development. For now, use the REST API directly or the CLI with --output json.

Previous← CLI Reference NextConfiguration →

Need help?

Ask a question in GitHub Discussions or check the troubleshooting guide.

Community Troubleshooting