{
  "openapi": "3.0.3",
  "info": {
    "title": "DNS Lookup",
    "version": "1.1.0",
    "description": "Public DNS lookup, no authentication. JSON API at /resolve, plus raw DNS-over-HTTPS (RFC 8484) at /, an MCP server at /mcp and an A2A agent at /a2a. See /llms.txt for a short guide.",
    "license": {
      "name": "Free to use"
    }
  },
  "servers": [
    {
      "url": "https://domainnamesystem.pages.dev"
    }
  ],
  "tags": [
    {
      "name": "lookup",
      "description": "DNS record lookup"
    },
    {
      "name": "agents",
      "description": "MCP and A2A interfaces"
    }
  ],
  "externalDocs": {
    "description": "Agent guide",
    "url": "https://domainnamesystem.pages.dev/llms.txt"
  },
  "paths": {
    "/resolve": {
      "get": {
        "operationId": "dnsLookup",
        "tags": [
          "lookup"
        ],
        "summary": "Look up DNS records for a domain",
        "description": "Returns the records found for the given name. Omitting `type` queries A, AAAA, CNAME, MX, TXT and NS. `type=ALL` queries every supported type. Check `status` and `hint`: NXDOMAIN means the domain does not exist; NOERROR with empty `answers` means it exists but has no records of the queried types.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Domain name to look up.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "example": "google.com"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": false,
            "description": "Comma-separated record types, e.g. `A,MX`. Omitted = A,AAAA,CNAME,MX,TXT,NS. `ALL` = every supported type (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA, HTTPS, SRV, PTR). SRV and PTR only return data at special names such as `_sip._tcp.example.com` or `10.2.0.192.in-addr.arpa`.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "A",
                  "AAAA",
                  "CNAME",
                  "MX",
                  "TXT",
                  "NS",
                  "SOA",
                  "CAA",
                  "HTTPS",
                  "SRV",
                  "PTR",
                  "ALL"
                ]
              },
              "default": [
                "A",
                "AAAA",
                "CNAME",
                "MX",
                "TXT",
                "NS"
              ]
            },
            "example": "A,MX"
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup result (also returned for NXDOMAIN / SERVFAIL; check `status`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResult"
                },
                "examples": {
                  "found": {
                    "summary": "Records found",
                    "value": {
                      "name": "google.com",
                      "status": "NOERROR",
                      "queried": [
                        "A",
                        "MX"
                      ],
                      "answers": [
                        {
                          "name": "google.com",
                          "type": "A",
                          "ttl": 300,
                          "data": "142.250.80.46"
                        },
                        {
                          "name": "google.com",
                          "type": "MX",
                          "ttl": 300,
                          "data": "10 smtp.google.com"
                        }
                      ]
                    }
                  },
                  "nxdomain": {
                    "summary": "Domain does not exist",
                    "value": {
                      "name": "no-such-domain-example.invalid",
                      "status": "NXDOMAIN",
                      "queried": [
                        "A",
                        "AAAA",
                        "CNAME",
                        "MX",
                        "TXT",
                        "NS"
                      ],
                      "answers": [],
                      "hint": "NXDOMAIN is a definitive answer: this domain name does not exist (not a lookup failure). Check the spelling and the TLD."
                    }
                  },
                  "empty": {
                    "summary": "Exists, no such records",
                    "value": {
                      "name": "example.com",
                      "status": "NOERROR",
                      "queried": [
                        "CNAME"
                      ],
                      "answers": [],
                      "hint": "The domain name exists but has no CNAME records. This is normal (e.g. CNAME is usually empty); try type=ALL to check every supported type."
                    }
                  }
                }
              }
            },
            "headers": {
              "Signature": {
                "description": "RFC 9421 signature, present when signing is enabled.",
                "schema": {
                  "type": "string"
                }
              },
              "Signature-Input": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Digest": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "dohGet",
        "tags": [
          "lookup"
        ],
        "summary": "Raw DNS-over-HTTPS query (RFC 8484, GET)",
        "description": "Without `dns` this returns the HTML home page (or Markdown when `Accept: text/markdown`).",
        "parameters": [
          {
            "name": "dns",
            "in": "query",
            "required": false,
            "description": "base64url-encoded DNS wire-format query (no padding).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DNS wire-format response.",
            "content": {
              "application/dns-message": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid DNS message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "dohPost",
        "tags": [
          "lookup"
        ],
        "summary": "Raw DNS-over-HTTPS query (RFC 8484, POST)",
        "requestBody": {
          "required": true,
          "content": {
            "application/dns-message": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DNS wire-format response.",
            "content": {
              "application/dns-message": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid DNS message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "tags": [
          "agents"
        ],
        "summary": "MCP server (Streamable HTTP, stateless JSON-RPC 2.0)",
        "description": "Methods: initialize, tools/list, tools/call (tool `dns_lookup` with `name` and optional `type`), ping. Batches are supported.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "dns_lookup",
                  "arguments": {
                    "name": "gmail.com",
                    "type": "MX"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted (no body)."
          }
        }
      }
    },
    "/a2a": {
      "post": {
        "operationId": "a2a",
        "tags": [
          "agents"
        ],
        "summary": "A2A agent (JSON-RPC 2.0, protocol 0.3.0, message/send)",
        "description": "Send a text part ('MX gmail.com', 'google.com') or a data part {\"name\":\"gmail.com\",\"type\":\"MX\"}. The reply message has a text part (JSON string) and a data part (object). Streaming and tasks are not supported.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "message/send",
                "params": {
                  "message": {
                    "kind": "message",
                    "role": "user",
                    "messageId": "m1",
                    "parts": [
                      {
                        "kind": "data",
                        "data": {
                          "name": "gmail.com",
                          "type": "MX"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LookupResult": {
        "type": "object",
        "required": [
          "name",
          "status",
          "queried",
          "answers"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Normalised domain name that was queried."
          },
          "status": {
            "type": "string",
            "description": "DNS RCODE.",
            "enum": [
              "NOERROR",
              "FORMERR",
              "SERVFAIL",
              "NXDOMAIN",
              "NOTIMP",
              "REFUSED"
            ]
          },
          "queried": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "A",
                "AAAA",
                "CNAME",
                "MX",
                "TXT",
                "NS",
                "SOA",
                "CAA",
                "HTTPS",
                "SRV",
                "PTR"
              ]
            },
            "description": "Record types actually looked up."
          },
          "answers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "A",
                    "AAAA",
                    "CNAME",
                    "MX",
                    "TXT",
                    "NS",
                    "SOA",
                    "CAA",
                    "HTTPS",
                    "SRV",
                    "PTR"
                  ]
                },
                "ttl": {
                  "type": "integer"
                },
                "data": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "type",
                "ttl",
                "data"
              ]
            },
            "description": "Records found; empty if none."
          },
          "hint": {
            "type": "string",
            "description": "Plain-language interpretation, present for empty results, errors and partial failures."
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "A",
                "AAAA",
                "CNAME",
                "MX",
                "TXT",
                "NS",
                "SOA",
                "CAA",
                "HTTPS",
                "SRV",
                "PTR"
              ]
            },
            "description": "Present only on partial failure: types that returned SERVFAIL while others succeeded."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "example": {
            "type": "string"
          },
          "supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
