Port Scanning

The port scanning endpoints let you retrieve scan results showing which ports are open on your server. This is useful for verifying expected ports are reachable on any monitor with the port scanning check enabled. The scans come from Oh Dear's TCP port monitoring, which flags unexpected open ports and expected ports found closed.

You'll need a monitor ID for these endpoints.

Example request:

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/monitors/1/ports-history-items \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

All endpoints below follow the same authentication pattern.

Port scan response fields #

Every port scan endpoint returns a scan result object with these fields:

{
  "id": 1,
  "scanned_host": "example.com",
  "resolved_ip": "93.184.216.34",
  "performed_on_checker_server": "port-checker-frankfurt-1",
  "continent": "europe",
  "open_ports": [80, 443],
  "issues": [
    {
      "name": "ExpectedOpenPortClosed",
      "ports": [8080]
    }
  ],
  "scan_time_ms": 1250,
  "created_at": "2024-06-15 14:30:00"
}

• id: unique identifier for this scan result
• scanned_host: the hostname that was scanned
• resolved_ip: the IPv4 address that was actually scanned (resolved from the hostname)
• performed_on_checker_server: the checker server that ran this scan. Persisted per scan, so historical results keep their original server even after the monitor's continent changes. null for scans recorded before this was tracked
• continent: the continent the scan ran from, derived from performed_on_checker_server. null when the server is unknown
• open_ports: array of port numbers found open during the scan
• issues: array of detected issues. Each contains a name and a ports array listing the affected port numbers. Possible issue names: ExpectedOpenPortClosed (a port on your expected-open list was found closed) and UnexpectedOpenPort (a port that is not on your expected-open list was found open)
• scan_time_ms: total time the scan took in milliseconds
• created_at: when this scan was performed (UTC)

Get a specific scan result #

GET /api/monitors/{monitorId}/ports-history-items/{portsHistoryItemId}

Returns a single port scan result by its ID. The response follows the scan result shape above.

List port scan history #

GET /api/monitors/{monitorId}/ports-history-items

Returns a paginated list of port scan results for a monitor. Each item follows the same scan result shape above.

Query parameters:

• filter[created_at] (string, optional) -- only return results created at or after this timestamp in YmdHis format, in UTC (e.g., 20240615000000)