@apifreaks/openapi-specs 0.1.0

package/specs/domain/domain-search.json

@@ -0,0 +1,206 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Domain Availability API - Check Domain Names in Real Time and Get Suggestions",
+    "version": "1.0.0",
+    "description": "Check whether a domain is available for registration across all top-level domains (TLDs) and second-level domains (SLDs). Uses DNS-based or WHOIS-based lookups to determine domain availability. Returns a simple response with the domain name and a boolean availability indicator.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Domain Search API Server"
+    }
+  ],
+  "paths": {
+    "/domain/availability": {
+      "get": {
+        "tags": ["Domain APIs"],
+        "summary": "Check whether a domain is available for registration or not.",
+        "description": "The Domain Search API is designed to simplify the process of finding available domain names across all top-level domains (TLDs) and second-level domains (SLDs).",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Format of the response."
+          },
+          {
+            "name": "domain",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Domain name whose availability is to be checked."
+          },
+          {
+            "name": "source",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["dns", "whois"],
+              "default": "dns"
+            },
+            "description": "Specify the data source for domain availability checks. Use \"dns\" for DNS-based lookups or \"whois\" for WHOIS-based lookups. By default, \"dns\" is used."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DomainAvailabilityResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Domain available",
+                    "value": {
+                      "domain": "google.com",
+                      "domainAvailability": false
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request – Missing domain, or domain has an unrecognized/unsupported TLD",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingDomain": {
+                    "summary": "Missing required domain parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/domain/availability",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:18:21.115Z"
+                    }
+                  },
+                  "unsupportedTld": {
+                    "summary": "Domain has an unrecognized or unsupported TLD",
+                    "value": {
+                      "timestamp": "2026-07-27T12:18:47.346748812Z",
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Please pass domain param correct value [For Technical Support: support@whoisfreaks.com]",
+                      "path": "/v1.0/domain/availability"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "408": {
+            "description": "Request Timeout – Unable to fetch WHOIS data",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "error": {
+                    "summary": "Error response",
+                    "value": {
+                      "timestamp": "2025-08-14T10:37:21.871Z",
+                      "status": 408,
+                      "error": "Request Timeout",
+                      "message": "Unable to fetch whois data. Please try again. [For Technical Support email at: support@apifreaks.com]",
+                      "path": "/v1.0/domain/availability"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "checkDomainAvailability"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "DomainAvailabilityResponse": {
+        "type": "object",
+        "required": ["domain", "domainAvailability"],
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "Name of the queried domain"
+          },
+          "domainAvailability": {
+            "type": "boolean",
+            "description": "True if available, false if not available"
+          }
+        },
+        "description": "Domain availability check response containing the domain name and availability status."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/domain/subdomain-lookup.json

@@ -0,0 +1,343 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Subdomain Finder API - Discover Active, Inactive & Historical Subdomains",
+    "version": "1.0.0",
+    "description": "Retrieve subdomains related to a given domain name. Returns paginated results with subdomain details including first seen and last seen dates. Supports filtering by date range, status (active/inactive), and pagination with configurable page numbers.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Subdomain Lookup API Server"
+    }
+  ],
+  "paths": {
+    "/subdomains/lookup": {
+      "get": {
+        "tags": ["Domain APIs"],
+        "summary": "Get subdomains related to the given domain name.",
+        "description": "The Subdomain Lookup API is designed to retrieve subdomains related to the given domain name. It helps you explore subdomains that are available for registration or usage.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Format of the response."
+          },
+          {
+            "name": "domain",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Domain name for availability and suggestions."
+          },
+          {
+            "name": "after",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "format": "date"
+            },
+            "description": "Filter subdomains seen after this date (format YYYY-MM-DD)."
+          },
+          {
+            "name": "before",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "format": "date"
+            },
+            "description": "Filter subdomains seen before this date( format YYYY-MM-DD)."
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["active", "inactive"],
+              "default": "active"
+            },
+            "description": "Filter subdomains by status (active or inactive)."
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 1
+            },
+            "description": "Page number for paginated results."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubDomainResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "domain": "google.com",
+                      "status": true,
+                      "query_time": "2026-07-27T12:22:26.954268895",
+                      "current_page": 1,
+                      "total_pages": 1543,
+                      "total_records": 154233,
+                      "subdomains": [
+                        {
+                          "subdomain": "49qq1sm.sites.google.com",
+                          "first_seen": "2024-03-03",
+                          "last_seen": "2026-06-18"
+                        },
+                        {
+                          "subdomain": "tvgkp5.feedproxy.ghs.google.com",
+                          "last_seen": "2026-07-04"
+                        },
+                        {
+                          "subdomain": "www.reusablesec.sites.google.com",
+                          "first_seen": "2020-02-18",
+                          "last_seen": "2026-06-20"
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request – one or more parameters are invalid",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingDomain": {
+                    "summary": "Missing required domain parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/subdomains/lookup",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:22:27.587Z"
+                    }
+                  },
+                  "invalidDomain": {
+                    "summary": "domain is not a syntactically valid domain name",
+                    "value": {
+                      "timestamp": "2026-07-27T12:22:40.119716922Z",
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Please pass domain param correct value[For Technical Support: support@whoisfreaks.com]",
+                      "path": "/v1.0/subdomains"
+                    }
+                  },
+                  "AfterDateError": {
+                    "summary": "after is not earlier than before",
+                    "value": {
+                      "timestamp": "2026-07-27T12:22:28.233751455Z",
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "after date must be earlier than before date.",
+                      "path": "/v1.0/subdomains"
+                    }
+                  },
+                  "AfterDateGreaterThanCurrent": {
+                    "summary": "after is in the future",
+                    "value": {
+                      "timestamp": "2026-07-27T12:22:39.061042798Z",
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "after date cannot be greater than the current date.",
+                      "path": "/v1.0/subdomains"
+                    }
+                  },
+                  "BeforeDateGreaterThanCurrent": {
+                    "summary": "before is in the future",
+                    "value": {
+                      "timestamp": "2026-07-27T12:22:39.609545647Z",
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "before date cannot be greater than the current date.",
+                      "path": "/v1.0/subdomains"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "408": {
+            "description": "Request Timeout – Unable to fetch WHOIS data",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "error": {
+                    "summary": "Error response",
+                    "value": {
+                      "timestamp": "2025-08-14T10:37:21.871Z",
+                      "status": 408,
+                      "error": "Request Timeout",
+                      "message": "Unable to fetch whois data. Please try again. [For Technical Support email at: support@apifreaks.com]",
+                      "path": "/v1.0/subdomains/lookup"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "lookupSubdomains"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "SubDomainResponse": {
+        "type": "object",
+        "required": [
+          "domain",
+          "status",
+          "query_time",
+          "current_page",
+          "total_pages",
+          "total_records",
+          "subdomains"
+        ],
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "The domain name for which subdomains are retrieved."
+          },
+          "status": {
+            "type": "boolean",
+            "description": "Indicates whether the request was successfully processed or not."
+          },
+          "query_time": {
+            "type": "string",
+            "description": "Timestamp showing when the API request was executed."
+          },
+          "current_page": {
+            "type": "integer",
+            "description": "The current page number of the paginated response."
+          },
+          "total_pages": {
+            "type": "integer",
+            "description": "Total number of pages available for the given query. Each page has 100 subdomain entries."
+          },
+          "total_records": {
+            "type": "integer",
+            "description": "Total number of subdomains found for the domain."
+          },
+          "subdomains": {
+            "type": "array",
+            "description": "Returns an array of subdomain objects. Each object contains detailed information about an individual subdomain.",
+            "items": {
+              "$ref": "#/components/schemas/SubdomainItem"
+            }
+          }
+        },
+        "description": "Subdomain lookup response containing paginated subdomain results."
+      },
+      "SubdomainItem": {
+        "type": "object",
+        "description": "A single subdomain record with discovery dates.",
+        "required": ["subdomain", "last_seen"],
+        "properties": {
+          "subdomain": {
+            "type": "string",
+            "description": "The discovered subdomain associated with the given domain."
+          },
+          "first_seen": {
+            "type": "string",
+            "format": "date",
+            "description": "The date when the subdomain was first discovered. Can be absent for some records."
+          },
+          "last_seen": {
+            "type": "string",
+            "format": "date",
+            "description": "The most recent date when the subdomain was observed."
+          },
+          "inactive_from": {
+            "type": "string",
+            "format": "date",
+            "description": "The date from which the subdomain is considered inactive. Appears only if inactive."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}