Heade.rs Heade.rs API

openapi: 3.2.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.


    The 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. GET https://heade.rs/api, with no query, reports on the caller''s own IP address.'
  contact:
    name: Colin Armstrong
    url: https://armstr.ng
servers:
- url: https://heade.rs
tags:
- name: Heade.rs API
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 not applicable.'
                      type:
                      - object
                      - 'null'
                    registration:
                      description: Domain registration, from RDAP or WHOIS.
                      type:
                      - object
                      - 'null'
                    allocation:
                      description: The regional registry's record for the address.
                      type:
                      - object
                      - 'null'
                    http:
                      description: The response to https://<domain>/.
                      type:
                      - object
                      - 'null'
                    certificate:
                      description: TLS certificate from CT.
                      type:
                      - object
                      - 'null'
                    email:
                      type:
                      - object
                      - 'null'
                      description: Mail provider, SPF, DMARC, MTA-STS, TLS-RPT and BIMI.
                    site:
                      type:
                      - object
                      - 'null'
                      description: Front page, platform, tech stack, AI crawler rules, security posture, agent offerings.
                    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 data.
                    registration:
                      type:
                      - object
                      - 'null'
      tags:
      - Heade.rs API
externalDocs:
  description: llms.txt
  url: https://heade.rs/llms.txt