API reference

Base URL

Examples below use https://steelsuit.com as the API origin. Replace it with the API origin shown in your dashboard if it differs.

Authentication

SteelSuit uses API keys. Create one under Dashboard → API keys — you accept the scan warranty once at creation and it covers every subsequent scan. Keys are prefixed sk_ and passed as a bearer token on every request:

curl https://steelsuit.com/api/v1/scans/<scan_id> \
  -H "Authorization: Bearer sk_your_key_here"

API access requires a plan with the API enabled (Pro). Keys are scoped to your account and inherit your plan's quotas.

Start a scan

The integration endpoint requires at least one delivery channel — results are pushed to you, so there's no need to poll.

POST /api/v1/integrations/scans
Authorization: Bearer sk_your_key_here
Content-Type: application/json

{
  "target": "example.com",
  "pipeline": "fast_scan",
  "delivery": [
    { "type": "webhook", "target": "https://your-app.com/hooks/steelsuit", "secret": "shared-secret" },
    { "type": "email" }
  ]
}

• pipeline — fast_scan (default) or deep_scan. pentest is not available over the API.
• delivery — 1 to 5 channels; type is webhook, email, or slack.
• webhook / slack — target is an HTTPS URL we POST to. For webhooks, an optional secret (8+ chars) signs the payload with X-SteelSuit-Signature: sha256=….
• email — target is optional; omit it to send to your account email. A provided address must match your account email.

Response — 202 Accepted:

{
  "scan_id": "0c7e…",
  "status": "queued",
  "result_url": "https://steelsuit.com/api/v1/scans/0c7e…/public?exp=…&sig=…",
  "delivery_count": 2,
  "queue_total": 1
}

result_url is an HMAC-signed link (valid 7 days) that anyone can open to view the result with no auth. It's also embedded in every delivery payload.

When the scan completes

Each delivery (webhook/email/slack) carries a summary envelope:

{
  "scan_id": "0c7e…",
  "domain": "example.com",
  "pipeline": "fast_scan",
  "status": "completed",
  "score": "B",
  "counts": { "critical": 0, "high": 1, "medium": 2, "low": 4, "info": 0 },
  "completed_at": "2026-05-22T17:40:00Z",
  "result_url": "https://steelsuit.com/api/v1/scans/0c7e…/public?exp=…&sig=…"
}

Webhooks retry with backoff (1m → 5m → 30m → 2h → 6h → 24h) until delivered or exhausted.

Read findings

Either follow result_url, or query directly with your key:

GET /api/v1/scans/{scan_id}/findings
Authorization: Bearer sk_your_key_here

Returns a JSON array; each finding has severity, category, title, description, evidence, recommendation, and cwe. Query params:

• severity=critical,high — comma-separated severity filter.
• include_info=true — include informational findings (excluded by default).
• format=llm — add a fix_prompt field per finding: a ready-to-paste prompt for an AI coding tool.

Other read endpoints:

• GET /api/v1/scans/{scan_id} — status, progress, and summary (score + counts).
• GET /api/v1/scans/{scan_id}/report.pdf — the external (client-facing) PDF report.

Errors

Errors return a non-2xx status with a JSON body like {"detail": {"error_code": "…", "msg": "…"}}:

• 401 — missing or invalid key.
• 403 — API not enabled on your plan, pentest requested, or the key predates warranty acceptance (rotate it).
• 409 — a scan for that domain is already queued or running.
• 429 — quota or rate limit reached.

Quotas

Plans carry three independent caps: total scans per period, deep scans per period, and the number of distinct domains. Exact numbers per plan are on your dashboard's plan page. Free does not include API access; Pro does.