Port Scan API — /api/v1/ip/port

Streams Server-Sent Events as each port is probed. Use `sync=true` to receive a single JSON object once every probe completes.

• Method GET
• Path /api/v1/ip/port
• Stability STABLE
• Version v2026-05-15
• Summary Check open/closed status of TCP ports on a host (SSE stream).

Pass these as query-string parameters (or, where indicated, in the request headers). Required params marked required.

• host (required) — string IP address or hostname to scan.
• ports (required) — string Comma-separated list of ports (0–65535). Example: `22,80,443,3306`.
• sync — boolean, default false When `true`, returns a single JSON response after the scan completes instead of streaming SSE.

All successful responses follow the standard `{ success: true, data: {...} }` envelope. Notable fields on the data object for this endpoint:

• event: port — SSE Per-port status. `data: {port, status, service}`.
• event: done — SSE Sent once after the final port. `data: {scanned, open, closed, elapsedMs}`.
• event: error — SSE Fatal error. `data: {code, message}`.

Truncated but representative example for a real lookup:

{
  "stream": [
    "event: port\ndata: {\"port\": 22, \"status\": \"open\", \"service\": \"ssh\"}\n\n",
    "event: port\ndata: {\"port\": 80, \"status\": \"open\", \"service\": \"http\"}\n\n",
    "event: port\ndata: {\"port\": 443, \"status\": \"closed\"}\n\n",
    "event: done\ndata: {\"scanned\": 3, \"open\": 2, \"closed\": 1, \"elapsedMs\": 1284}\n\n"
  ]
}

Errors return HTTP status codes paired with stable machine-readable codes. Match on the code field rather than the human-readable message.

• 400 INVALID_PORTS One or more ports outside 0–65535.
• 504 HOST_TIMEOUT Host refused all probes — likely firewalled.

Patterns we recommend when integrating this endpoint:

• Keep `ports` under 100 per request — anything larger should be chunked.
• Don't scan hosts you don't own without permission. We log and rate-limit aggressive scanners.
• Prefer SSE in browsers; use `sync=true` from CLI/scripts.

• Do you support UDP? Not currently. TCP only.