API Documentation

Multi-provider lookup (ip-api.com → ipwho.is → ipinfo.io) with failover, 24h cache, reverse DNS, threat flags, and meta (provider, cached, elapsedMs). Omitting data returns the caller's IP. SSRF-guarded.

Parameters

Cache: public, max-age=300, s-maxage=3600

Queries Cloudflare, Google, and Quad9 over DNS-over-HTTPS. Returns per-resolver answers, DNSSEC status (validated/secure/bogus/none), cross-resolver diff, homograph/punycode flags.

Cache: public, max-age=60, s-maxage=600

HEAD request with redirect-chain tracking (max 5 hops, each hop validated), HTTP version, full headers, and a 0-100 security score with per-header checks.

Concurrent engine (32 workers, randomized timeout jitter, banner capture). Range syntax 80,443,8000-8010, max 50 ports.

SSE: ?stream=1 emits start, progress, result, done events with 15s heartbeats.

Status: /api/portscan?scanId={id} returns snapshot; scans expire after 10 minutes.

Chain walk with per-level verification, OCSP revocation check (AIA responder), TLS version matrix (1.0-1.3), cipher negotiation probe, and 0-100 security score with breakdown + letter grade.

Allowed ports: 80, 443, 465, 993, 995, 8443

RDAP-first with IANA bootstrap (cached 24h), fallback to raw port-43 WHOIS at whois.iana.org. Normalized fields: registrar, dates, nameservers, status codes, abuse contact, DNSSEC flag. Supports domains, IP ranges (inetnum), and AS{number}.

Cache: public, max-age=3600, s-maxage=86400

Subdomain discovery from crt.sh with certspotter fallback. Deduplicated names, wildcard badges, issuer lists, first/last seen, and an issuance timeline. Cached 24h (crt.sh is slow).

Create an async job. Body: { tool: "dns"|"ip"|"ssl", items: ["a.com","8.8.8.8",...], webhookUrl?, webhookSecret? }. Max 200 unique items, concurrency 5, per-item pacing, automatic retry (2x), TTL 15 min.

Job snapshot: status (created/queued/running/partial/done/failed/aborted), progress, ETA, results.

SSE events: start, progress, item, done.

Abort a running job.

Body: { payload: { tool, query, result } } (max 8KB). Returns Crockford base32 code (8 chars), share URL, expiry (7 days).

Retrieve payload. Cache: public, max-age=3600, s-maxage=86400. Response includes ownerToken for deletion.

Delete a share (owner token required).

SVG OpenGraph preview card for social embeds.

Client-only mode: #/share/{base64url-json} renders without server round-trip.

Generates a human-language diagnostic summary via an OpenAI-compatible provider. Requires AI_API_KEY env. Results cached 24h (zero re-bill), daily budget guardrail (BUDGET_DAILY_USD), circuit breaker on repeated failures.

SSE: ?stream=1 streams data: {"token": "..."} chunks.

Memory, uptime, upstream reachability (rdap.org, Cloudflare DoH, crt.sh). Returns 503 when degraded. Exempt from rate limits.

Rate-limit stats, cache hit ratios, error counts, active scans/jobs, KV mode. Exempt from rate limits.

Interactive Playground

Try any endpoint live. Response is validated against the OpenAPI contract in development mode.

"Press Run to fetch"

Error Codes

Webhooks (HMAC-Signed)

Pass webhookUrl + webhookSecret when creating a batch job. On completion the engine POSTs:

POST {webhookUrl}
Headers:
  X-Webhook-Signature: sha256={hex HMAC-SHA256 of raw body using webhookSecret}
  X-Webhook-Event: scan.completed
  X-Webhook-Idempotency-Key: {jobId}:{attempt}
Body: { "event":"scan.completed", "scanId":"...", "tool":"dns",
        "status":"done", "timestamp":"...", "attempt":1,
        "summary":{ "total":150, "ok":148, "failed":2 },
        "results":[ {item,status,result} ] }

Retries: 3 attempts with 1s/5s/30s backoff, 10s timeout. Verify the signature server-side with your secret — never trust an unauthenticated webhook.

Rate Limits

Sliding window (60s) + token bucket. Headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After. Client IP taken from the first x-forwarded-for value. Optional Upstash Redis backend via UPSTASH_REDIS_REST_URL.