Skip to content

Instantly share code, notes, and snippets.

@LukasSchauffele
Created July 1, 2025 00:48
Show Gist options
  • Save LukasSchauffele/7dd5dd49f87d9b55aae6bd8daa426d86 to your computer and use it in GitHub Desktop.
Save LukasSchauffele/7dd5dd49f87d9b55aae6bd8daa426d86 to your computer and use it in GitHub Desktop.
{
"openapi": "3.0.3",
"info": {
"title": "WhoisJson API - Documentation",
"description": "RESTful API for domain and network information lookups. Provides WHOIS data, DNS records, SSL certificate details, and domain availability checks.\n\n### Available Operations\n- **WHOIS Lookup**: Retrieve domain registration information including owner contacts, registrar details, and status\n- **Reverse WHOIS**: Get domain information from IP addresses\n- **DNS Lookup**: Query DNS records (A, AAAA, MX, NS, SOA) for domains\n- **SSL Certificate Check**: Validate and retrieve SSL certificate details\n- **Domain Availability**: Check if domains are available for registration\n- **Random WHOIS**: Retrieve sample WHOIS records from the database\n\n### Authentication\nRequires API key authentication via Authorization header: `TOKEN=<YOUR_API_KEY>`\n\n### Response Formats\nSupports both JSON and XML response formats. JSON is the default format.\n\n### Rate Limiting\nAPI usage is tracked and limited. Remaining request count is returned in the `Remaining-Requests` response header.\n\n### HTTP Status Codes\n| Status Code | Description | Reason |\n| ----------- | ----------- | ------ |\n| 200 | Successful operation | Request completed successfully |\n| 400 | Bad Request | Invalid request parameters |\n| 401 | Unauthorized | Invalid or missing API key |\n| 403 | Access Denied | Account not validated or insufficient permissions |\n| 429 | Rate Limited | API usage limit exceeded |\n| 500 | Internal Error | Server error occurred |",
"version": "1.0.0"
},
"servers": [
{
"url": "https://whoisjson.com/api/v1"
}
],
"tags": [
{
"name": "Requests",
"description": "Everything you need to know about our API"
}
],
"paths": {
"/whois": {
"get": {
"tags": [
"Requests"
],
"summary": "Get Whois data",
"description": "Use WHOIS lookup to check domain name availability and to discover the contact information of a domain owner.",
"operationId": "getwhois",
"parameters": [
{
"name": "domain",
"in": "query",
"description": "Domain name requested",
"required": true,
"explode": true,
"schema": {
"type": "string",
"default": "whoisjson.com"
}
},
{
"name": "format",
"in": "query",
"description": "Format of the response",
"required": false,
"explode": true,
"schema": {
"type": "string",
"default": "json",
"enum": [
"json",
"xml"
]
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Whois"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Whois"
}
}
}
}
}
}
},
"/nslookup": {
"get": {
"tags": [
"Requests"
],
"summary": "Find DNS records for a domain name",
"description": "NsLookup queries the specified DNS server and retrieves the requested records that are associated with the domain name you provided.",
"operationId": "nslookup",
"parameters": [
{
"name": "domain",
"in": "query",
"description": "The domain name you want to look up.",
"required": true,
"explode": true,
"schema": {
"type": "string",
"default": "whoisjson.com"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Nslookup"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Nslookup"
}
}
}
}
}
}
},
"/ssl-cert-check": {
"get": {
"tags": [
"Requests"
],
"summary": "Retrieve SSL Certificate Details for a Domain",
"description": "The SSL Cert Check endpoint retrieves and validates the SSL certificate details for a specified domain, including issuer information, validity period, and current status. This endpoint helps ensure that the SSL certificate is correctly installed and up to date.",
"operationId": "sslcertcheck",
"parameters": [
{
"name": "domain",
"in": "query",
"description": "The domain name for which you want to retrieve the SSL certificate details.",
"required": true,
"explode": true,
"schema": {
"type": "string",
"default": "whoisjson.com"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SSL-Cert-Check"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/SSL-Cert-Check"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Whois": {
"type": "object",
"properties": {
"server": {
"type": "string",
"description": "The whois server that provided the domain information",
"example": "delta"
},
"name": {
"type": "string",
"description": "The queried domain name",
"example": "whoisjson.com"
},
"idnName": {
"type": "string",
"description": "The internationalized domain name (IDN) representation of the domain",
"example": "whoisjson.com"
},
"status": {
"type": "array",
"description": "Array of domain status codes indicating current restrictions or protections",
"items": {
"type": "string",
"description": "Individual domain status code with optional reference URL",
"example": "clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited"
}
},
"nameserver": {
"type": "array",
"description": "List of authoritative name servers for the domain",
"items": {
"type": "string",
"description": "Name server hostname",
"example": "dns200.anycast.me"
}
},
"ips": {
"type": "string",
"description": "IP address(es) associated with the domain",
"example": "62.210.113.88"
},
"created": {
"type": "string",
"description": "Date and time when the domain was first registered",
"example": "2016-12-01 09:28:12"
},
"changed": {
"type": "string",
"description": "Date and time when the domain registration was last modified",
"example": "2021-12-02 00:13:57"
},
"expires": {
"type": "string",
"description": "Date and time when the domain registration expires",
"example": "2022-12-01 10:28:12"
},
"registered": {
"type": "boolean",
"description": "Indicates whether the domain is currently registered",
"example": true
},
"dnssec": {
"type": "string",
"description": "DNSSEC status of the domain (e.g., signedDelegation, unsigned)",
"example": "signedDelegation"
},
"whoisserver": {
"type": "string",
"description": "The authoritative whois server for this domain",
"example": "whois.ovh.com"
},
"contacts": {
"type": "object",
"description": "Contact information for the domain including owner, admin, and technical contacts",
"properties": {
"owner": {
"type": "array",
"description": "Domain owner/registrant contact information",
"items": {
"type": "object",
"properties": {
"handle": {
"type": "string",
"description": "Unique identifier for this contact record"
},
"type": {
"type": "string",
"description": "Type of contact (e.g., person, organization)"
},
"name": {
"type": "string",
"description": "Full name of the contact person"
},
"organization": {
"type": "string",
"description": "Organization or company name"
},
"email": {
"type": "string",
"description": "Email address of the contact"
},
"address": {
"type": "string",
"description": "Street address of the contact"
},
"zipcode": {
"type": "string",
"description": "Postal/ZIP code"
},
"city": {
"type": "string",
"description": "City name"
},
"state": {
"type": "string",
"description": "State or province"
},
"country": {
"type": "string",
"description": "Country name or code"
},
"phone": {
"type": "string",
"description": "Phone number"
},
"fax": {
"type": "string",
"description": "Fax number"
},
"created": {
"type": "string",
"description": "Date when this contact record was created"
},
"changed": {
"type": "string",
"description": "Date when this contact record was last modified"
}
}
}
},
"admin": {
"type": "array",
"description": "Administrative contact information for the domain",
"items": {
"type": "object",
"properties": {
"handle": {
"type": "string",
"description": "Unique identifier for this contact record"
},
"type": {
"type": "string",
"description": "Type of contact (e.g., person, organization)"
},
"name": {
"type": "string",
"description": "Full name of the contact person"
},
"organization": {
"type": "string",
"description": "Organization or company name"
},
"email": {
"type": "string",
"description": "Email address of the contact"
},
"address": {
"type": "string",
"description": "Street address of the contact"
},
"zipcode": {
"type": "string",
"description": "Postal/ZIP code"
},
"city": {
"type": "string",
"description": "City name"
},
"state": {
"type": "string",
"description": "State or province"
},
"country": {
"type": "string",
"description": "Country name or code"
},
"phone": {
"type": "string",
"description": "Phone number"
},
"fax": {
"type": "string",
"description": "Fax number"
},
"created": {
"type": "string",
"description": "Date when this contact record was created"
},
"changed": {
"type": "string",
"description": "Date when this contact record was last modified"
}
}
}
},
"tech": {
"type": "array",
"description": "Technical contact information for the domain",
"items": {
"type": "object",
"properties": {
"handle": {
"type": "string",
"description": "Unique identifier for this contact record"
},
"type": {
"type": "string",
"description": "Type of contact (e.g., person, organization)"
},
"name": {
"type": "string",
"description": "Full name of the contact person"
},
"organization": {
"type": "string",
"description": "Organization or company name"
},
"email": {
"type": "string",
"description": "Email address of the contact"
},
"address": {
"type": "string",
"description": "Street address of the contact"
},
"zipcode": {
"type": "string",
"description": "Postal/ZIP code"
},
"city": {
"type": "string",
"description": "City name"
},
"state": {
"type": "string",
"description": "State or province"
},
"country": {
"type": "string",
"description": "Country name or code"
},
"phone": {
"type": "string",
"description": "Phone number"
},
"fax": {
"type": "string",
"description": "Fax number"
},
"created": {
"type": "string",
"description": "Date when this contact record was created"
},
"changed": {
"type": "string",
"description": "Date when this contact record was last modified"
}
}
}
}
}
},
"registrar": {
"type": "object",
"description": "Information about the domain registrar",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the registrar",
"example": 433
},
"name": {
"type": "string",
"description": "Name of the registrar company",
"example": "OVH, SAS"
},
"email": {
"type": "string",
"description": "Contact email address for the registrar",
"example": "[email protected]"
},
"url": {
"type": "string",
"description": "Website URL of the registrar",
"example": "https://www.ovh.com"
},
"phone": {
"type": "string",
"description": "Phone number of the registrar",
"example": 33.972101007
}
}
},
"rawdata": {
"type": "array",
"description": "Raw whois response data as returned by the whois server",
"items": {
"type": "string",
"description": "Individual line from the raw whois response"
}
},
"network": {
"type": "string",
"description": "Network information associated with the domain or IP"
},
"exception": {
"type": "string",
"description": "Error message if any exception occurred during the whois lookup"
},
"parsedContacts": {
"type": "boolean",
"description": "Indicates whether contact information was successfully parsed from the whois data",
"example": true
},
"template": {
"type": "object",
"description": "Template information used for parsing the whois data",
"properties": {
"string": {
"type": "string",
"description": "Template string identifier"
}
}
},
"ask_whois": {
"type": "string",
"description": "The whois server that was queried for this information",
"example": "whois.ovh.com"
},
"source": {
"type": "string",
"description": "Data source used for the lookup (whois, rdap, etc.)",
"example": "whois | rdap"
}
}
},
"Nslookup": {
"type": "object",
"properties": {
"A": {
"type": "array",
"description": "IPv4 address records for the domain",
"items": {
"type": "string",
"description": "IPv4 address",
"example": "188.114.96.2"
}
},
"AAAA": {
"type": "array",
"description": "IPv6 address records for the domain",
"items": {
"type": "string",
"description": "IPv6 address",
"example": "2a06:98c1:3120::2"
}
},
"MX": {
"type": "array",
"description": "Mail exchange records for the domain",
"items": {
"type": "object",
"description": "Mail exchange record with server and priority",
"properties": {
"exchange": {
"type": "string",
"description": "Mail server hostname",
"example": "mailstream-central.mxrecord.mx"
},
"priority": {
"type": "integer",
"description": "Priority value for the mail server (lower values have higher priority)",
"example": 20
}
}
}
},
"NS": {
"type": "array",
"description": "Name server records for the domain",
"items": {
"type": "string",
"description": "Name server hostname",
"example": "fish.ns.cloudflare.com"
}
},
"SOA": {
"type": "object",
"description": "Start of Authority record containing authoritative information about the domain",
"properties": {
"nsname": {
"type": "string",
"description": "Primary name server for the domain",
"example": "fish.ns.cloudflare.com"
},
"hostmaster": {
"type": "string",
"description": "Email address of the domain administrator (with @ replaced by .)",
"example": "dns.cloudflare.com"
},
"serial": {
"type": "integer",
"description": "Serial number of the zone, used for zone transfer synchronization",
"example": 2287007851
},
"refresh": {
"type": "integer",
"description": "Time interval (in seconds) before secondary name servers should check for updates",
"example": 10000
},
"retry": {
"type": "integer",
"description": "Time interval (in seconds) secondary name servers should wait before retrying a failed zone transfer",
"example": 2400
},
"expire": {
"type": "integer",
"description": "Time interval (in seconds) after which secondary name servers should stop answering queries if they cannot contact the primary",
"example": 604800
},
"minttl": {
"type": "integer",
"description": "Minimum time-to-live (in seconds) for DNS records in this zone",
"example": 3600
}
}
}
}
},
"SSL-Cert-Check": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "The domain name for which the SSL certificate was checked",
"example": "whoisjson.com"
},
"issuer": {
"type": "object",
"description": "Information about the Certificate Authority that issued the SSL certificate",
"properties": {
"C": {
"type": "string",
"description": "Country code of the certificate issuer",
"example": "US"
},
"O": {
"type": "string",
"description": "Organization name of the certificate issuer",
"example": "Let's Encrypt"
},
"CN": {
"type": "string",
"description": "Common name of the certificate issuer",
"example": "R3"
}
}
},
"valid_from": {
"type": "string",
"description": "ISO 8601 formatted date and time when the certificate becomes valid",
"example": "2024-04-01T12:58:12.000Z"
},
"valid_to": {
"type": "string",
"description": "ISO 8601 formatted date and time when the certificate expires",
"example": "2024-06-30T12:58:11.000Z"
},
"valid": {
"type": "boolean",
"description": "Indicates whether the SSL certificate is currently valid",
"example": true
},
"details": {
"type": "object",
"description": "Detailed information about the SSL certificate",
"properties": {
"subject": {
"type": "object",
"description": "Subject information of the certificate",
"properties": {
"CN": {
"type": "string",
"description": "Common name (domain) for which the certificate was issued",
"example": "whoisjson.com"
}
}
},
"issuer": {
"type": "object",
"description": "Detailed issuer information within certificate details",
"properties": {
"C": {
"type": "string",
"description": "Country code of the certificate issuer",
"example": "US"
},
"O": {
"type": "string",
"description": "Organization name of the certificate issuer",
"example": "Let's Encrypt"
},
"CN": {
"type": "string",
"description": "Common name of the certificate issuer",
"example": "R3"
}
}
},
"subjectaltname": {
"type": "string",
"description": "Subject Alternative Names - additional domains covered by this certificate",
"example": "DNS:whoisjson.com, DNS:www.whoisjson.com"
},
"ca": {
"type": "boolean",
"description": "Indicates whether this certificate can be used as a Certificate Authority",
"example": false
},
"modulus": {
"type": "string",
"description": "RSA public key modulus (hexadecimal representation)",
"example": "D614368313A15BF69116B613C8632E..."
},
"bits": {
"type": "integer",
"description": "Key size in bits (e.g., 2048, 4096)",
"example": 2048
},
"exponent": {
"type": "string",
"description": "RSA public key exponent",
"example": 65537
},
"pubkey": {
"type": "object",
"description": "Public key information in buffer format",
"properties": {
"type": {
"type": "string",
"description": "Data type identifier",
"example": "Buffer"
},
"data": {
"type": "array",
"description": "Array of bytes representing the public key",
"items": {
"type": "integer",
"description": "Individual byte value",
"example": "48, 130"
}
}
}
},
"valid_from": {
"type": "string",
"description": "Human-readable format of certificate validity start date",
"example": "Apr 1 12:58:12 2024 GMT"
},
"valid_to": {
"type": "string",
"description": "Human-readable format of certificate expiration date",
"example": "Jun 30 12:58:11 2024 GMT"
},
"fingerprint": {
"type": "string",
"description": "SHA-1 fingerprint of the certificate",
"example": "33:9F:69:28:A0:88:62:C7:80:EB:D5:A5:06:8C:97:0A:87:35:AF:BE"
},
"fingerprint256": {
"type": "string",
"description": "SHA-256 fingerprint of the certificate",
"example": "85:70:14:19:D2:F6:ED:7A:9E:22:1C..."
},
"fingerprint512": {
"type": "string",
"description": "SHA-512 fingerprint of the certificate",
"example": "13:0F:5C:96:BD:D9:6F:24:A7:F3:C9:36..."
},
"ext_key_usage": {
"type": "array",
"description": "Extended key usage object identifiers",
"items": {
"type": "string",
"description": "Object identifier for extended key usage",
"example": "1.3.6.1.5.5.7.3.1"
}
},
"serialNumber": {
"type": "string",
"description": "Unique serial number assigned to the certificate by the issuer",
"example": "03213ECA313DE36923BDF7C3FFB02AFA12ED"
},
"raw": {
"type": "object",
"description": "Raw certificate data in buffer format",
"properties": {
"type": {
"type": "string",
"description": "Data type identifier",
"example": "Buffer"
},
"data": {
"type": "array",
"description": "Array of bytes representing the raw certificate",
"items": {
"type": "integer",
"description": "Individual byte value",
"example": "13, 41, 55"
}
}
}
}
}
}
}
}
},
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"description": "Must be Token=YOUR_API_KEY"
}
}
},
"security": [
{
"ApiKeyAuth": []
}
]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment