Created
July 1, 2025 00:48
-
-
Save LukasSchauffele/7dd5dd49f87d9b55aae6bd8daa426d86 to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "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