{"info":{"title":"Controllo Porte API","version":"4.0.1","description":"controlloporte.it offers an API for checking port availability on specified hostnames or IP addresses. Ideal for developers and network admins, it helps troubleshoot network setups, validate firewall rules, and assess potential access points."},"openapi":"3.1.0","servers":[{"url":"https://controlloporte.it"}],"paths":{"/api/me":{"get":{"summary":"MyIp","description":"Returns the requester IP.\n\nAuto-detects the public IP address associated with the incoming request.","operationId":"ApiMeMyIp","responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"text/plain":{"schema":{"type":"string","description":"The IP address of the requester","examples":["1.1.1.1"]}}}}},"deprecated":false}},"/api/controlloDDNS":{"post":{"summary":"ControlloDdnsPost","description":"Compare a DNS hostname with the requester public IP address.\n\nThe endpoint resolves the supplied hostname to an IPv4 address and compares it\nwith the public IP detected from the request headers. It is useful to verify\nwhether a dynamic DNS hostname currently points to the same public IP used by\nthe visitor.","operationId":"ApiControlloddnsControlloDdnsPost","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDNSCheckSchema"}}},"required":true},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDNSResponseSchema"}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":false}},"/api/query":{"post":{"summary":"QueryPost","description":"A `POST` endpoint to query the status of multiple ports on a given hostname\nor IP address.\n\nThis endpoint accepts a JSON payload containing either a public IPv4 address\nor a resolvable hostname, along with an array of TCP port numbers to be checked.\nUse `me` as the host to auto-detect the requester IP address based\non the incoming request. In that case, the response `host` field contains\nthe resolved requester public IP address. The `ports` values must be integers,\nnot strings.\nDNS resolution is performed once before the TCP checks, so `latency_ms` does not\ninclude DNS lookup time. For each port in the array, the endpoint performs a TCP\nconnectivity check with a timeout of 1 second per port. Open ports include the\nTCP connection latency in milliseconds. Closed or unreachable ports return\n`latency_ms: null`.","operationId":"ApiQueryQueryPost","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APISchema"}}},"required":true},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIResponseSchema"}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":false}},"/api/{host}/{port}":{"get":{"summary":"GetPortCheck","description":"Legacy plain text `GET` endpoint to check one TCP port.\n\nUse `me` as the host to auto-detect the requester IP address based\non the incoming request.\n\nThis endpoint returns `True` or `False` as `text/plain`.\nFor JSON responses with latency, use `/api/check/{host}/{port}`.","operationId":"ApiHostPortGetPortCheck","parameters":[{"name":"host","in":"path","schema":{"type":"string","maxLength":253,"minLength":1,"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","examples":["example.com","1.1.1.1","me"]},"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","required":true,"deprecated":false,"examples":{"host-example-1":{"value":"example.com"},"host-example-2":{"value":"1.1.1.1"},"host-example-3":{"value":"me"}}},{"name":"port","in":"path","schema":{"type":"integer","maximum":65535.0,"minimum":1.0,"description":"The port number to query","examples":[443]},"description":"The port number to query","required":true,"deprecated":false,"examples":{"port-example-1":{"value":443}}}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"text/plain":{"schema":{"type":"string","description":"Whether the port was connectable","examples":["True"]}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":false}},"/api/check/{host}/{port}":{"get":{"summary":"GetPortCheckJson","description":"JSON `GET` endpoint to check one TCP port.\n\nUse `me` as the host to auto-detect the requester IP address based\non the incoming request.\n\nDNS resolution is performed before the TCP check. The response uses the same\nstructure as `POST /api/query`. Open ports include `latency_ms`, the TCP\nconnection latency in milliseconds. Closed or unreachable ports return\n`latency_ms: null`.","operationId":"ApiCheckHostPortGetPortCheckJson","parameters":[{"name":"host","in":"path","schema":{"type":"string","maxLength":253,"minLength":1,"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","examples":["example.com","1.1.1.1","me"]},"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","required":true,"deprecated":false,"examples":{"host-example-1":{"value":"example.com"},"host-example-2":{"value":"1.1.1.1"},"host-example-3":{"value":"me"}}},{"name":"port","in":"path","schema":{"type":"integer","maximum":65535.0,"minimum":1.0,"description":"The port number to query","examples":[443]},"description":"The port number to query","required":true,"deprecated":false,"examples":{"port-example-1":{"value":443}}}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIResponseSchema"}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":false}},"/api/nat/quick-scan":{"post":{"summary":"QuickNatScanPost","description":"Run a quick NAT scan against the requester public IPv4 address.\n\nThe client must provide explicit consent. The endpoint never accepts a target IP\nfrom the request body; it scans only the public IP detected from proxy headers.","operationId":"ApiNatQuickScanQuickNatScanPost","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NATScanRequestSchema"}}},"required":true},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NATScanResponseSchema"}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":false}},"/api/v1/query":{"post":{"summary":"V1QueryPost","description":"A `POST` endpoint to query the status of multiple ports on a given hostname\nor IP address.\n\nThis deprecated endpoint accepts a JSON payload containing either a public IPv4\naddress or a resolvable hostname, along with an array of TCP port numbers to be\nchecked. The `ports` values must be integers, not strings.\nFor each port in the array, the endpoint performs a connectivity check with a\ntimeout of 1 second per port. Open ports include `latency_ms`, the TCP connection\nlatency in milliseconds. Closed or unreachable ports return `latency_ms: null`.\n\n**NOTE:** The request body for this endpoint is not logged.\n~~~\n\"POST /api/query HTTP/1.1\" 200 OK\n~~~","operationId":"ApiV1QueryV1QueryPost","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APISchema"}}},"required":true},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIResponseSchema"}}}},"400":{"description":"Bad request syntax or unsupported method","content":{"application/json":{"schema":{"properties":{"status_code":{"type":"integer"},"detail":{"type":"string"},"extra":{"additionalProperties":{},"type":["null","object","array"]}},"type":"object","required":["detail","status_code"],"description":"Validation Exception","examples":[{"status_code":400,"detail":"Bad Request","extra":{}}]}}}}},"deprecated":true}},"/healthz":{"get":{"summary":"Health","description":"Basic health check to ensure API is responding. Returns `True`.","operationId":"HealthzHealth","responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"type":"boolean"}}}}},"deprecated":false}}},"components":{"schemas":{"APICheckSchema":{"properties":{"port":{"type":"integer","maximum":65535.0,"minimum":1.0,"description":"The port number to query","examples":[443]},"status":{"type":"boolean","description":"Whether the port was connectable","examples":[true]},"latency_ms":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"TCP connection latency in milliseconds when the port is open. Null when the port is closed or unreachable.","examples":[23]}},"type":"object","required":["port","status"],"title":"APICheckSchema"},"APIResponseSchema":{"properties":{"error":{"type":"boolean","description":"Whether an error occurred during the check","examples":[false]},"msg":{"oneOf":[{"type":"string"},{"type":"null"}]},"check":{"items":{"$ref":"#/components/schemas/APICheckSchema"},"type":"array"},"host":{"type":"string","description":"Host that was checked. When the request uses `me`, this is the resolved requester public IP address.","examples":["example.com","1.1.1.1"]}},"type":"object","required":["check","error","host"],"title":"APIResponseSchema"},"APISchema":{"properties":{"host":{"type":"string","maxLength":253,"minLength":1,"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","examples":["example.com","1.1.1.1","me"]},"ports":{"items":{"type":"integer","maximum":65535.0,"minimum":1.0,"description":"The port number to query","examples":[443]},"type":"array","description":"TCP port numbers to check. Values must be integers from 1 to 65535.","examples":[[80,443]]}},"type":"object","required":["host","ports"],"title":"APISchema","description":"Query a resolvable hostname, public IPv4 address, or use `me` to check the requester public IP address."},"DDNSCheckSchema":{"properties":{"host":{"type":"string","maxLength":253,"minLength":1,"description":"Resolvable hostname, public IPv4 address, or `me` to use the requester public IP address.","examples":["example.com","1.1.1.1","me"]}},"type":"object","required":["host"],"title":"DDNSCheckSchema","description":"Resolve a hostname and compare it with the public IP address detected for the incoming request."},"DDNSResponseSchema":{"properties":{"error":{"type":"boolean","description":"Whether an error occurred during the check","examples":[false]},"msg":{"oneOf":[{"type":"string"},{"type":"null"}]},"host":{"type":"string","description":"Hostname that was resolved","examples":["casa.example.com"]},"requester_ip":{"type":"string","description":"Public IP address detected for the requester","examples":["1.2.3.4"]},"resolved_ip":{"type":"string","description":"IPv4 address resolved from the hostname","examples":["1.2.3.4"]},"match":{"type":"boolean","description":"Whether the requester public IP matches the hostname resolution","examples":[true]}},"type":"object","required":["error","host","match","requester_ip","resolved_ip"],"title":"DDNSResponseSchema"},"NATScanNotShownSchema":{"properties":{"count":{"type":"integer","description":"Number of non-open ports not shown","examples":[48]},"state":{"type":"string","description":"Dominant state for non-open ports","examples":["filtered"]},"reason":{"type":"string","description":"Dominant reason for non-open ports","examples":["no-response"]}},"type":"object","required":["count","reason","state"],"title":"NATScanNotShownSchema"},"NATScanOpenPortSchema":{"properties":{"port":{"type":"integer","description":"TCP port number","examples":[443]},"protocol":{"type":"string","description":"Protocol scanned","examples":["tcp"]},"state":{"type":"string","description":"Nmap state","examples":["open"]},"service":{"type":"string","description":"Detected or known service name","examples":["https"]},"reason":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Nmap reason","examples":["syn-ack"]}},"type":"object","required":["port","protocol","service","state"],"title":"NATScanOpenPortSchema"},"NATScanRequestSchema":{"properties":{"consent":{"type":"boolean","description":"Explicit user confirmation that they want to scan their detected public IP address and are authorized to do so.","examples":[true]}},"type":"object","required":["consent"],"title":"NATScanRequestSchema","description":"Runs a controlled nmap top-ports scan against the requester public IPv4 address. The target IP is always detected from the request and cannot be supplied by the client."},"NATScanResponseSchema":{"properties":{"ip":{"type":"string","description":"Requester public IPv4 address","examples":["91.99.156.172"]},"scan_type":{"type":"string","description":"Scan profile","examples":["top_ports"]},"num_ports":{"type":"integer","description":"Number of top ports scanned","examples":[50]},"scanned_ports":{"type":"integer","description":"Number of TCP ports scanned","examples":[50]},"open_ports":{"items":{"$ref":"#/components/schemas/NATScanOpenPortSchema"},"type":"array"},"not_shown":{"$ref":"#/components/schemas/NATScanNotShownSchema"},"duration_ms":{"type":"integer","description":"Scan duration in milliseconds","examples":[12340]},"error":{"type":"boolean","description":"Whether an error occurred","examples":[false]},"msg":{"oneOf":[{"type":"string"},{"type":"null"}]},"summary":{"type":"string","description":"Short human-readable interpretation of the result","examples":["Sono state trovate 2 porte raggiungibili dall'esterno."]},"report":{"type":"string","description":"Italian nmap-like report text"}},"type":"object","required":["duration_ms","error","ip","not_shown","num_ports","open_ports","report","scan_type","scanned_ports","summary"],"title":"NATScanResponseSchema"}}}}