@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/domain/subdomain-lookup.yaml

@@ -0,0 +1,251 @@
+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: []

package/dist/specs/email-validation/bulk-email-validation.yaml

@@ -0,0 +1,403 @@
+openapi: 3.1.1
+info:
+  title: Bulk Email Validation API - Validate and Verify Emails in Bulk
+  version: 1.0.0
+  description: Validate up to 100 email addresses in a single POST request. Each email is processed independently. Returns an array of validation results with deliverability assessment per email, plus per-item error objects for failed validations. Maximum 100 email addresses per request.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Bulk Email Validation API Server
+paths:
+  /email-validation/bulk:
+    post:
+      tags:
+        - Email Validation APIs
+      summary: Validate multiple email addresses
+      description: Validates a bulk of email addresses and returns result for each. Maximum `100` email addresses per request.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: Format of the response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkEmailRequest'
+      responses:
+        '200':
+          description: Successful response. Each item corresponds to one requested email, in the same order as the request; invalid emails are reflected via validEmail/validSyntax on that item, not as a separate error object — every item has success=true regardless of validation outcome.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkEmailValidationResponse'
+              examples:
+                bulkEmailsValidated:
+                  summary: Mix of a valid and a syntactically invalid email
+                  value:
+                    emailValidationResponses:
+                      - success: true
+                        email: abc.def@gmail.com
+                        validEmail: valid
+                        validSyntax: true
+                        domain:
+                          name: gmail.com
+                          disposable: false
+                          spam: false
+                          free: true
+                          validDomain: true
+                          catchAll: false
+                        account:
+                          role: false
+                          fullMailBox: false
+                        dns:
+                          mxRecords:
+                            - gmail-smtp-in.l.google.com.
+                            - alt1.gmail-smtp-in.l.google.com.
+                            - alt2.gmail-smtp-in.l.google.com.
+                            - alt3.gmail-smtp-in.l.google.com.
+                            - alt4.gmail-smtp-in.l.google.com.
+                      - success: true
+                        email: not-an-email
+                        validEmail: INVALID_EMAIL
+                        validSyntax: false
+                        domain:
+                          name: not-an-email
+                          validDomain: false
+        '400':
+          description: Bad Request – Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidBody:
+                  summary: emailData field missing or malformed
+                  value:
+                    timestamp: '2026-07-27T12:53:14.628Z'
+                    path: /v1.0/email-validation/bulk
+                    status: 400
+                    error: Invalid request body Exception
+                    message: Please provide data in required format in request body
+        '408':
+          description: Request Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                Request Timeout:
+                  value:
+                    timestamp: '2026-06-06T13:00:00.000Z'
+                    path: /v1.0/email-validation/bulk
+                    status: 408
+                    error: Request Timeout
+                    message: Timed out while connecting to the remote URL.
+        '429':
+          description: Rate Limit Exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                Rate Limit Exceeded:
+                  value:
+                    timestamp: '2026-06-06T13:00:00.000Z'
+                    path: /v1.0/email-validation/bulk
+                    status: 429
+                    error: Too Many Requests
+                    message: API rate limit exceeded.
+      operationId: bulkCheckEmail
+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:
+    BulkEmailValidationResponse:
+      type: object
+      description: Wrapper containing the per-email results array.
+      required:
+        - emailValidationResponses
+      properties:
+        emailValidationResponses:
+          type: array
+          description: Array of per-email results, one entry per requested email, in the same order as the request. Invalid emails are reflected via validEmail/validSyntax, not a separate error shape.
+          items:
+            $ref: '#/components/schemas/SingleEmailValidationResponse'
+    SingleEmailValidationResponse:
+      type: object
+      required:
+        - success
+        - email
+        - validEmail
+        - validSyntax
+        - domain
+      properties:
+        success:
+          type: boolean
+          description: 'Indicates the processing status of the validation request. true: completed successfully.'
+        email:
+          type: string
+          format: email
+          description: The email address submitted for validation.
+        name:
+          type: string
+          description: Optional identifier or label provided in the request for record tracking.
+        reason:
+          type: string
+          description: Detailed explanation returned when validEmail is not valid.
+        validEmail:
+          type: string
+          enum:
+            - valid
+            - invalid
+            - INVALID_EMAIL
+            - unknown
+            - risky
+          description: 'Comprehensive deliverability assessment. Casing is inconsistent in the live API: syntactically invalid addresses return INVALID_EMAIL, while semantically invalid (undeliverable) addresses return lowercase invalid. unknown/risky are documented possibilities not observed during testing.'
+        validSyntax:
+          type: boolean
+          description: Validates email address format compliance with RFC 5322 standards.
+        domain:
+          $ref: '#/components/schemas/DomainObject'
+        account:
+          $ref: '#/components/schemas/AccountObject'
+        dns:
+          $ref: '#/components/schemas/DnsObject'
+        address:
+          $ref: '#/components/schemas/AddressObject'
+        ip:
+          type: string
+          format: ip
+          description: IP address provided for geolocation and security enrichment.
+      description: Email validation response containing deliverability assessment and metadata.
+    DomainObject:
+      type: object
+      required:
+        - name
+        - validDomain
+      properties:
+        name:
+          type: string
+          description: Extracted domain component from the email address.
+        validDomain:
+          type: boolean
+          description: Domain validation status confirming DNS resolution capability.
+        disposable:
+          type: boolean
+          description: Classification flag identifying domains from temporary email service providers.
+        spam:
+          type: boolean
+          description: Reputation indicator flagging domains on spam databases.
+        free:
+          type: boolean
+          description: Classification indicating free or consumer-grade email service providers.
+        catchAll:
+          type: boolean
+          description: Detection flag for domains configured to accept mail for any recipient address.
+      description: Domain validation details for the email address.
+    AccountObject:
+      type: object
+      required:
+        - role
+      properties:
+        role:
+          type: boolean
+          description: Detection flag identifying role-based email addresses (e.g., admin@, support@).
+        fullMailBox:
+          type: boolean
+          description: Storage capacity status indicator for the recipient mailbox.
+      description: Account-level validation details.
+    DnsObject:
+      type: object
+      required:
+        - mxRecords
+      properties:
+        mxRecords:
+          type: array
+          items:
+            type: string
+          description: Collection of MX (Mail Exchange) hostname records from DNS queries.
+        aRecords:
+          type: array
+          items:
+            type: string
+          description: Collection of A (Address) records for the domain. Not observed in testing — may be rarely or never populated.
+      description: DNS records for the email domain.
+    AddressObject:
+      type: object
+      properties:
+        validIpAddress:
+          type: boolean
+          description: IP recognized/reachable by the geolocation provider.
+        location:
+          $ref: '#/components/schemas/EmailLocation'
+        security:
+          $ref: '#/components/schemas/EmailSecurity'
+      description: Geolocation and security enrichment data for the IP address.
+      required: []
+    EmailLocation:
+      type: object
+      description: Geolocation data derived from the IP address.
+      properties:
+        city:
+          type: string
+          description: Municipal or city name.
+        district:
+          type: string
+          description: District or neighborhood.
+        zipcode:
+          type: string
+          description: Postal or ZIP code.
+        state_prov:
+          type: string
+          description: State or province.
+        country_name:
+          type: string
+          description: Common country name.
+        country_name_official:
+          type: string
+          description: Official country name.
+        country_code2:
+          type: string
+          description: Two-character ISO country code.
+        country_code3:
+          type: string
+          description: Three-character ISO country code.
+        continent_name:
+          type: string
+          description: Continental region name.
+        continent_code:
+          type: string
+          description: Continental region identifier.
+        accuracy_radius:
+          type: string
+          description: Geolocation precision radius.
+        confidence:
+          type: string
+          description: Confidence score for geolocation accuracy.
+        is_eu:
+          type: boolean
+          description: European Union membership status.
+      required: []
+    EmailSecurity:
+      type: object
+      description: Threat and anonymity profile for the IP address.
+      required:
+        - threat_score
+        - is_tor
+        - is_proxy
+        - proxy_type
+        - proxy_provider
+        - is_anonymous
+        - is_known_attacker
+        - is_spam
+        - is_bot
+        - is_cloud_provider
+        - cloud_provider
+      properties:
+        threat_score:
+          type: integer
+          description: Quantitative risk assessment score. Higher values indicate elevated security risk.
+        is_tor:
+          type: boolean
+          description: Detection flag for IP addresses routed through the Tor anonymity network.
+        is_proxy:
+          type: boolean
+          description: Detection flag identifying IP addresses operating as proxy servers.
+        proxy_type:
+          type: string
+          description: Classification of detected proxy infrastructure type (e.g. VPN, HTTP, SOCKS).
+        proxy_provider:
+          type: string
+          description: Identified service provider operating the proxy infrastructure.
+        is_anonymous:
+          type: boolean
+          description: Anonymization detection flag for IP addresses using identity obfuscation techniques.
+        is_known_attacker:
+          type: boolean
+          description: Threat intelligence flag for IP addresses documented as confirmed malicious sources.
+        is_spam:
+          type: boolean
+          description: Reputation flag for IP addresses associated with spam transmission.
+        is_bot:
+          type: boolean
+          description: Automated traffic detection flag for IP addresses from bot networks.
+        is_cloud_provider:
+          type: boolean
+          description: Infrastructure classification flag for IP addresses from cloud computing providers.
+        cloud_provider:
+          type: string
+          description: Identified cloud infrastructure or hosting service provider name.
+    BulkEmailRequest:
+      type: object
+      description: Request body for bulk email validation.
+      required:
+        - emailData
+      properties:
+        emailData:
+          type: array
+          description: Array of email objects to validate. Maximum 100 per request.
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/BulkEmailRequestItem'
+    BulkEmailRequestItem:
+      type: object
+      description: A single email entry in a bulk validation request.
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+          description: Email address to validate.
+        name:
+          type: string
+          description: Optional name or label.
+        ip:
+          type: string
+          format: ip
+          description: Optional IP address for enrichment.
+    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: []