{ "openapi": "3.1.0", "info": { "title": "heade.rs API", "version": "1.0.0", "summary": "Look up any domain or IP address: where it's hosted, which networks carry your traffic there, how fast it answers, and who registered it.", "description": "Free web tool at heade.rs, made by Colin Armstrong, that looks up any domain, IP address or network (AS number) and reports its hosting, routes, latency, registration, DNS, email security, HTTP headers and support for AI crawlers and agents.\n\nThe same reports are Markdown at https://heade.rs/ for requests whose Accept header prefers text/markdown, and plain text for curl. Agents can also use the MCP server at https://heade.rs/mcp. No key or account; 30 lookups a minute per client.", "contact": { "name": "Colin Armstrong", "url": "https://armstr.ng" } }, "externalDocs": { "description": "llms.txt", "url": "https://heade.rs/llms.txt" }, "servers": [ { "url": "https://heade.rs" } ], "paths": { "/api/{query}": { "get": { "operationId": "lookup", "summary": "Look up a domain, IP address or network", "description": "The full report as JSON. A domain or IP address gets hosting, registration, DNS, email security, HTTPS, the website's tech stack and AI crawler rules, and open ports; an AS number gets its prefixes, peering and registration. Takes a few seconds.", "parameters": [ { "name": "query", "in": "path", "required": true, "description": "A domain (example.com), IPv4 or IPv6 address, AS number (AS13335) or URL.", "schema": { "type": "string" }, "examples": { "domain": { "value": "github.com" }, "ipv4": { "value": "1.1.1.1" }, "network": { "value": "AS13335" } } } ], "responses": { "200": { "description": "A report. Reserved addresses and networks (private ranges, documentation ASNs) get { target, reserved } instead.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Host report", "type": "object", "properties": { "target": { "type": "object", "description": "What was looked up: kind (domain, ipv4, ipv6), value and display." }, "generatedAt": { "type": "string", "format": "date-time" }, "resolution": { "type": "object", "description": "Its IPv4 and IPv6 addresses, and the CNAME chain." }, "ip": { "type": [ "object", "null" ], "description": "The first address: network, BGP prefix, RPKI, location, hosting, reverse DNS." }, "dns": { "description": "DNS records. Either { ok: true, value } or { ok: false, reason } when the source failed; null when it doesn't apply.", "type": [ "object", "null" ] }, "registration": { "description": "Domain registration, from RDAP or WHOIS. Either { ok: true, value } or { ok: false, reason } when the source failed; null when it doesn't apply.", "type": [ "object", "null" ] }, "allocation": { "description": "The regional registry's record for the address. Either { ok: true, value } or { ok: false, reason } when the source failed; null when it doesn't apply.", "type": [ "object", "null" ] }, "http": { "description": "The response to https:///: status, headers, redirects, timing. Either { ok: true, value } or { ok: false, reason } when the source failed; null when it doesn't apply.", "type": [ "object", "null" ] }, "certificate": { "description": "The TLS certificate, from Certificate Transparency. Either { ok: true, value } or { ok: false, reason } when the source failed; null when it doesn't apply.", "type": [ "object", "null" ] }, "email": { "type": [ "object", "null" ], "description": "Mail provider, SPF, DMARC, MTA-STS, TLS-RPT and BIMI." }, "site": { "type": [ "object", "null" ], "description": "For domains: the front page, platform, tech stack, AI crawler rules (ai), security posture and what it offers agents (agents)." }, "exposure": { "type": [ "object", "null" ], "description": "Open ports, software and possible CVEs from Shodan InternetDB." } } }, { "title": "Network report", "type": "object", "properties": { "asn": { "type": "integer" }, "generatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "country": { "type": "string" }, "routes": { "type": [ "object", "null" ], "description": "Prefixes, address space and RPKI coverage." }, "peering": { "type": [ "object", "null" ], "description": "PeeringDB: exchanges, facilities, policy; and the ASPA record." }, "registration": { "type": [ "object", "null" ] } } } ] } } } }, "400": { "description": "No query.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "empty", "invalid", "unknown-tld", "rate-limited" ] }, "input": { "type": "string" }, "suggestion": { "type": "string", "description": "A likely fix for a mistyped top-level domain: example.com for example.con." }, "retryAfter": { "type": "integer", "description": "Seconds to wait, when rate-limited." } } } } } }, "404": { "description": "Not a domain, IP address or AS number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "empty", "invalid", "unknown-tld", "rate-limited" ] }, "input": { "type": "string" }, "suggestion": { "type": "string", "description": "A likely fix for a mistyped top-level domain: example.com for example.con." }, "retryAfter": { "type": "integer", "description": "Seconds to wait, when rate-limited." } } } } } }, "429": { "description": "More than 30 lookups in a minute.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "empty", "invalid", "unknown-tld", "rate-limited" ] }, "input": { "type": "string" }, "suggestion": { "type": "string", "description": "A likely fix for a mistyped top-level domain: example.com for example.con." }, "retryAfter": { "type": "integer", "description": "Seconds to wait, when rate-limited." } } } } } } } } }, "/api/activity": { "get": { "operationId": "activity", "summary": "Live lookups", "description": "The latest lookups on heade.rs, and the most looked-up names of the past 7 days.", "responses": { "200": { "description": "The lists.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }