API

API Documentation

All endpoints are served from https://ipconfig.sh. Responses are UTF-8 encoded.

Response Format

Chosen in this order: the fmt parameter (json, text, on some endpoints html), then an Accept: application/json header, then the User-Agent. Command-line tools and HTTP libraries (curl, wget, PowerShell, HTTPie, python-requests, Go, Node.js, …) get plain text; browsers get the web page. Errors and rate-limit responses use the same format. Every text and JSON response ends with a newline.

curl ipconfig.sh/help lists all commands.

Rate Limiting

All public endpoints are rate-limited. Exceeding limits returns a 429 status with a Retry-After header indicating when to retry. Respect the header and back off.

Authentication

All endpoints are public and require no authentication.

Error Responses

Standard HTTP status codes are used; JSON errors look like {"error": "..."}. Unknown paths count extra against the rate limit.

GET /

Returns the client's public IP address.

ParameterInTypeReqDescription
fmtquerystringNoOverrides the User-Agent detected default format:
text (default for CLI)
json
html (default for browsers)

Rate limit group:
global

Status:
200, 429

curl ipconfig.sh curl "ipconfig.sh/?fmt=json"
import requests # Plain text (python-requests gets text by default) ip = requests.get("https://ipconfig.sh").text.strip() # JSON data = requests.get("https://ipconfig.sh", params={"fmt": "json"}).json()
# Plain text (Invoke-WebRequest ipconfig.sh).Content # JSON Invoke-RestMethod "ipconfig.sh/?fmt=json"
Example Response
# Plain text 203.0.113.42 # JSON {"ip": "203.0.113.42"}

GET /whoami

Returns the client's IP, hostname, provider, ASN, and route.

ParameterInTypeReqDescription
fmtquerystringNoOverrides the User-Agent detected default format:
text (default)
json

Rate limit group:
global

Status:
200, 429

curl ipconfig.sh/whoami curl "ipconfig.sh/whoami?fmt=json"
import requests info = requests.get("https://ipconfig.sh/whoami", params={"fmt": "json"}).json() print(info["provider"], info["asn"])
Invoke-RestMethod "ipconfig.sh/whoami?fmt=json"
Example Response
# Plain text IP: 203.0.113.42 Hostname: host.example.com Provider: Example ISP Network: AS12345 - 203.0.113.0/24 Country: CH # JSON { "status": "ok", "ip": "203.0.113.42", "hostname": "host.example.com", "provider": "Example ISP", "provider_group": "Example Group", "asn": "AS12345", "route": "203.0.113.0/24", "country_code": "CH" }

GET /ip, /json, /help

Short aliases for scripts. <code>/ip</code>: just the IP, also in browsers. <code>/json</code>: everything <code>/whoami</code> knows, as JSON. <code>/help</code>: all commands as plain text (browsers are redirected to this page).

Rate limit group:
global

Status:
200, 429

curl ipconfig.sh/ip curl ipconfig.sh/json curl ipconfig.sh/help
import requests info = requests.get("https://ipconfig.sh/json").json() print(info["ip"], info["asn"])
Invoke-RestMethod ipconfig.sh/json
Example Response
{ "ip": "203.0.113.42", "hostname": "host.example.net", "provider": "Example ISP AG", "provider_group": "Example ISP", "asn": "AS64500", "route": "203.0.113.0/24", "country_code": "CH" }

GET /calc/<ip>/<prefix>

Calculate subnet information for an IPv4 or IPv6 network.

ParameterInTypeReqDescription
ippathstringYesIPv4 or IPv6 address
prefixpathintegerYesCIDR prefix (0-32 for v4, 0-128 for v6)
fmtquerystringNoOverrides the User-Agent detected default format:
text (default for CLI)
json
html (default for browsers)
splitqueryintegerNoSplit subnet at this prefix length

Rate limit group:
calc

Status:
200, 400, 429

curl ipconfig.sh/calc/10.0.0.0/24 curl "ipconfig.sh/calc/10.0.0.0/24?fmt=json" curl "ipconfig.sh/calc/10.0.0.0/24?split=26"
import requests calc = requests.get( "https://ipconfig.sh/calc/10.0.0.0/24", params={"fmt": "json"}).json()
Invoke-RestMethod ` "ipconfig.sh/calc/10.0.0.0/24?fmt=json"
Example Response
# Plain text (excerpt) Network: 10.0.0.0/24 Netmask: 255.255.255.0 Broadcast: 10.0.0.255 First: 10.0.0.1 Last: 10.0.0.254 Hosts: 254

GET /scan/<query>

Threat intelligence lookup for an IP, domain, subnet, or URL.

ParameterInTypeReqDescription
querypathstringYesIP, domain, subnet, or URL (max 2000 chars)
fmtquerystringNoOverrides the User-Agent detected default format:
text (default if omitted)
json
html

Rate limit group:
threat_intel

Status:
200, 400, 429

curl ipconfig.sh/scan/8.8.8.8 curl "ipconfig.sh/scan/example.com?fmt=json" curl ipconfig.sh/scan/192.168.0.0/16
import requests # Plain text print(requests.get( "https://ipconfig.sh/scan/8.8.8.8").text) # JSON threat = requests.get( "https://ipconfig.sh/scan/example.com", params={"fmt": "json"}).json() print(threat["threat_level"])
# Plain text (Invoke-WebRequest ` "ipconfig.sh/scan/8.8.8.8").Content # JSON Invoke-RestMethod ` "ipconfig.sh/scan/example.com?fmt=json"
Example Response
# JSON (excerpt) { "query": "8.8.8.8", "input_type": "ip", "threat_level": 0, "verdict": { "category": null, "label": "clean" }, "geoip": { "country_code": "US", "country_name": "United States" }, "dns": {"ptr": ["dns.google"]}, "raw_entries": [], "sources": [] }