@apifreaks/openapi-specs 0.3.0 → 0.3.1

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

@@ -2,7 +2,7 @@ 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.
+  description: Validate up to 10 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 10 email addresses per request.
   contact:
     name: APIFreaks Support
     url: https://apifreaks.com/contact
@@ -16,7 +16,7 @@ paths:
       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.
+      description: Validates a bulk of email addresses and returns result for each. Maximum `10` email addresses per request.
       parameters:
         - name: format
           in: query
@@ -45,7 +45,7 @@ paths:
                 bulkEmailsValidated:
                   summary: Mix of a valid and a syntactically invalid email
                   value:
-                    emailValidationResponses:
+                    emailResponse:
                       - success: true
                         email: abc.def@gmail.com
                         validEmail: valid
@@ -61,7 +61,7 @@ paths:
                           role: false
                           fullMailBox: false
                         dns:
-                          mxRecords:
+                          mxRecord:
                             - gmail-smtp-in.l.google.com.
                             - alt1.gmail-smtp-in.l.google.com.
                             - alt2.gmail-smtp-in.l.google.com.
@@ -77,6 +77,10 @@ paths:
           headers:
             X-AF-Credits-Cost:
               $ref: '#/components/headers/X-AF-Credits-Cost'
+            X-Concurrent-Threads:
+              $ref: '#/components/headers/X-Concurrent-Threads'
+            X-Concurrent-Threads-Active:
+              $ref: '#/components/headers/X-Concurrent-Threads-Active'
         '400':
           description: Bad Request – Invalid request body
           content:
@@ -95,6 +99,23 @@ paths:
           headers:
             X-AF-Credits-Cost:
               $ref: '#/components/headers/X-AF-Credits-Cost'
+        '404':
+          description: Not Found – The requested resource could not be found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                Resource Not Found:
+                  value:
+                    timestamp: '2026-09-02T11:57:55.592Z'
+                    path: /v1.0/email-validation/bulkx
+                    status: 404
+                    error: Resource Not Found
+                    message: The requested resource could not be found. Please verify the URL and try again.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '408':
           description: Request Timeout
           content:
@@ -112,6 +133,23 @@ paths:
           headers:
             X-AF-Credits-Cost:
               $ref: '#/components/headers/X-AF-Credits-Cost'
+        '413':
+          description: Payload Too Large – emailData exceeds the maximum of 10 entries per request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                Payload Too Large:
+                  value:
+                    timestamp: '2026-09-02T11:57:34.223Z'
+                    path: /v2/email-validation/bulk
+                    status: 413
+                    error: Payload too large Exception
+                    message: Maximum request body size limit exceeded
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '429':
           description: Rate Limit Exceeded
           content:
@@ -147,9 +185,9 @@ components:
       type: object
       description: Wrapper containing the per-email results array.
       required:
-        - emailValidationResponses
+        - emailResponse
       properties:
-        emailValidationResponses:
+        emailResponse:
           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:
@@ -184,7 +222,8 @@ components:
             - 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.'
+            - app_server_blocked
+          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. risky is a documented possibility not observed during testing. app_server_blocked is returned when the recipient mail server blocked the live verification attempt (reason explains that retrying later may succeed).'
         validSyntax:
           type: boolean
           description: Validates email address format compliance with RFC 5322 standards.
@@ -241,14 +280,14 @@ components:
     DnsObject:
       type: object
       required:
-        - mxRecords
+        - mxRecord
       properties:
-        mxRecords:
+        mxRecord:
           type: array
           items:
             type: string
           description: Collection of MX (Mail Exchange) hostname records from DNS queries.
-        aRecords:
+        aRecord:
           type: array
           items:
             type: string
@@ -367,8 +406,8 @@ components:
       properties:
         emailData:
           type: array
-          description: Array of email objects to validate. Maximum 100 per request.
-          maxItems: 100
+          description: Array of email objects to validate. Maximum 10 per request.
+          maxItems: 10
           items:
             $ref: '#/components/schemas/BulkEmailRequestItem'
     BulkEmailRequestItem:
@@ -415,6 +454,14 @@ components:
       description: Specifies the number of credits consumed by the current request.
       schema:
         type: integer
+    X-Concurrent-Threads:
+      description: Specifies the maximum number of concurrent requests allowed.
+      schema:
+        type: integer
+    X-Concurrent-Threads-Active:
+      description: Indicates the number of active concurrent requests being processed.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

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

@@ -2,7 +2,7 @@ openapi: 3.1.1
 info:
   title: Email Checker API - Real-Time Validation, Deliverability & Risk Signals
   version: 1.0.0
-  description: Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/invalid/unknown/risky status.
+  description: Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/invalid/unknown/risky/app_server_blocked status.
   contact:
     name: APIFreaks Support
     url: https://apifreaks.com/contact
@@ -59,7 +59,7 @@ paths:
                       role: false
                       fullMailBox: false
                     dns:
-                      mxRecords:
+                      mxRecord:
                         - gmail-smtp-in.l.google.com.
                         - alt1.gmail-smtp-in.l.google.com.
                         - alt2.gmail-smtp-in.l.google.com.
@@ -110,7 +110,7 @@ paths:
                       role: false
                       fullMailBox: false
                     dns:
-                      mxRecords:
+                      mxRecord:
                         - gmail-smtp-in.l.google.com.
                         - alt1.gmail-smtp-in.l.google.com.
                         - alt2.gmail-smtp-in.l.google.com.
@@ -145,6 +145,26 @@ paths:
                         is_bot: false
                         is_cloud_provider: true
                         cloud_provider: Google LLC
+                appServerBlocked:
+                  summary: Valid syntax, but the recipient mail server blocked the verification attempt
+                  value:
+                    success: true
+                    email: randomuser98765zzz@gmx.com
+                    validEmail: app_server_blocked
+                    validSyntax: true
+                    reason: We are unable to determine the validity of email at the moment. Please try later.
+                    domain:
+                      name: gmx.com
+                      disposable: false
+                      spam: false
+                      free: true
+                      validDomain: true
+                      catchAll: false
+                    account:
+                      role: false
+                    dns:
+                      mxRecord:
+                        - mx00.gmx.net.
           headers:
             X-AF-Credits-Cost:
               $ref: '#/components/headers/X-AF-Credits-Cost'
@@ -162,10 +182,10 @@ paths:
                 missingEmail:
                   summary: email field missing from request body
                   value:
-                    timestamp: '2026-07-27T12:51:23.593986185Z'
-                    path: /v2.0/email-validation/single
+                    timestamp: '2026-09-02T11:56:23.462Z'
+                    path: /v2/email-validation/single
                     status: 400
-                    error: External API Error
+                    error: Missing or Invalid Parameters
                     message: Please pass valid value for 'email' in body.
           headers:
             X-AF-Credits-Cost:
@@ -174,6 +194,27 @@ paths:
               $ref: '#/components/headers/X-Concurrent-Threads'
             X-Concurrent-Threads-Active:
               $ref: '#/components/headers/X-Concurrent-Threads-Active'
+        '404':
+          description: Not Found – The requested resource could not be found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                Resource Not Found:
+                  value:
+                    timestamp: '2026-09-02T11:56:23.937Z'
+                    path: /v1.0/email-validation/singlex
+                    status: 404
+                    error: Resource Not Found
+                    message: The requested resource could not be found. Please verify the URL and try again.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+            X-Concurrent-Threads:
+              $ref: '#/components/headers/X-Concurrent-Threads'
+            X-Concurrent-Threads-Active:
+              $ref: '#/components/headers/X-Concurrent-Threads-Active'
         '408':
           description: Request Timeout
           content:
@@ -260,7 +301,8 @@ components:
             - 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.'
+            - app_server_blocked
+          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. risky is a documented possibility not observed during testing. app_server_blocked is returned when the recipient mail server blocked the live verification attempt (reason explains that retrying later may succeed).'
         validSyntax:
           type: boolean
           description: Validates email address format compliance with RFC 5322 standards.
@@ -317,14 +359,14 @@ components:
     DnsObject:
       type: object
       required:
-        - mxRecords
+        - mxRecord
       properties:
-        mxRecords:
+        mxRecord:
           type: array
           items:
             type: string
           description: Collection of MX (Mail Exchange) hostname records from DNS queries.
-        aRecords:
+        aRecord:
           type: array
           items:
             type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apifreaks/openapi-specs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Public OpenAPI 3.1 specifications for all APIFreaks API products.",
   "type": "module",
   "main": "./dist/index.js",

package/specs/email-validation/bulk-email-validation.json

@@ -3,7 +3,7 @@
   "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.",
+    "description": "Validate up to 10 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 10 email addresses per request.",
     "contact": {
       "name": "APIFreaks Support",
       "url": "https://apifreaks.com/contact",
@@ -21,7 +21,7 @@
       "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.",
+        "description": "Validates a bulk of email addresses and returns result for each. Maximum `10` email addresses per request.",
         "parameters": [
           {
             "name": "format",
@@ -57,7 +57,7 @@
                   "bulkEmailsValidated": {
                     "summary": "Mix of a valid and a syntactically invalid email",
                     "value": {
-                      "emailValidationResponses": [
+                      "emailResponse": [
                         {
                           "success": true,
                           "email": "abc.def@gmail.com",
@@ -76,7 +76,7 @@
                             "fullMailBox": false
                           },
                           "dns": {
-                            "mxRecords": [
+                            "mxRecord": [
                               "gmail-smtp-in.l.google.com.",
                               "alt1.gmail-smtp-in.l.google.com.",
                               "alt2.gmail-smtp-in.l.google.com.",
@@ -104,6 +104,12 @@
             "headers": {
               "X-AF-Credits-Cost": {
                 "$ref": "#/components/headers/X-AF-Credits-Cost"
+              },
+              "X-Concurrent-Threads": {
+                "$ref": "#/components/headers/X-Concurrent-Threads"
+              },
+              "X-Concurrent-Threads-Active": {
+                "$ref": "#/components/headers/X-Concurrent-Threads-Active"
               }
             }
           },
@@ -134,6 +140,58 @@
               }
             }
           },
+          "404": {
+            "description": "Not Found – The requested resource could not be found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Resource Not Found": {
+                    "value": {
+                      "timestamp": "2026-09-02T11:57:55.592Z",
+                      "path": "/v1.0/email-validation/bulkx",
+                      "status": 404,
+                      "error": "Resource Not Found",
+                      "message": "The requested resource could not be found. Please verify the URL and try again."
+                    }
+                  }
+                }
+              }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
+            }
+          },
+          "413": {
+            "description": "Payload Too Large – emailData exceeds the maximum of 10 entries per request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Payload Too Large": {
+                    "value": {
+                      "timestamp": "2026-09-02T11:57:34.223Z",
+                      "path": "/v2/email-validation/bulk",
+                      "status": 413,
+                      "error": "Payload too large Exception",
+                      "message": "Maximum request body size limit exceeded"
+                    }
+                  }
+                }
+              }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
+            }
+          },
           "408": {
             "description": "Request Timeout",
             "content": {
@@ -210,9 +268,9 @@
       "BulkEmailValidationResponse": {
         "type": "object",
         "description": "Wrapper containing the per-email results array.",
-        "required": ["emailValidationResponses"],
+        "required": ["emailResponse"],
         "properties": {
-          "emailValidationResponses": {
+          "emailResponse": {
             "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": {
@@ -244,8 +302,15 @@
           },
           "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."
+            "enum": [
+              "valid",
+              "invalid",
+              "INVALID_EMAIL",
+              "unknown",
+              "risky",
+              "app_server_blocked"
+            ],
+            "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. risky is a documented possibility not observed during testing. app_server_blocked is returned when the recipient mail server blocked the live verification attempt (reason explains that retrying later may succeed)."
           },
           "validSyntax": {
             "type": "boolean",
@@ -319,16 +384,16 @@
       },
       "DnsObject": {
         "type": "object",
-        "required": ["mxRecords"],
+        "required": ["mxRecord"],
         "properties": {
-          "mxRecords": {
+          "mxRecord": {
             "type": "array",
             "items": {
               "type": "string"
             },
             "description": "Collection of MX (Mail Exchange) hostname records from DNS queries."
           },
-          "aRecords": {
+          "aRecord": {
             "type": "array",
             "items": {
               "type": "string"
@@ -484,8 +549,8 @@
         "properties": {
           "emailData": {
             "type": "array",
-            "description": "Array of email objects to validate. Maximum 100 per request.",
-            "maxItems": 100,
+            "description": "Array of email objects to validate. Maximum 10 per request.",
+            "maxItems": 10,
             "items": {
               "$ref": "#/components/schemas/BulkEmailRequestItem"
             }
@@ -548,6 +613,18 @@
         "schema": {
           "type": "integer"
         }
+      },
+      "X-Concurrent-Threads": {
+        "description": "Specifies the maximum number of concurrent requests allowed.",
+        "schema": {
+          "type": "integer"
+        }
+      },
+      "X-Concurrent-Threads-Active": {
+        "description": "Indicates the number of active concurrent requests being processed.",
+        "schema": {
+          "type": "integer"
+        }
       }
     }
   },

package/specs/email-validation/email-checker.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Email Checker API - Real-Time Validation, Deliverability & Risk Signals",
     "version": "1.0.0",
-    "description": "Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/invalid/unknown/risky status.",
+    "description": "Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/invalid/unknown/risky/app_server_blocked status.",
     "contact": {
       "name": "APIFreaks Support",
       "url": "https://apifreaks.com/contact",
@@ -73,7 +73,7 @@
                         "fullMailBox": false
                       },
                       "dns": {
-                        "mxRecords": [
+                        "mxRecord": [
                           "gmail-smtp-in.l.google.com.",
                           "alt1.gmail-smtp-in.l.google.com.",
                           "alt2.gmail-smtp-in.l.google.com.",
@@ -137,7 +137,7 @@
                         "fullMailBox": false
                       },
                       "dns": {
-                        "mxRecords": [
+                        "mxRecord": [
                           "gmail-smtp-in.l.google.com.",
                           "alt1.gmail-smtp-in.l.google.com.",
                           "alt2.gmail-smtp-in.l.google.com.",
@@ -178,6 +178,30 @@
                         }
                       }
                     }
+                  },
+                  "appServerBlocked": {
+                    "summary": "Valid syntax, but the recipient mail server blocked the verification attempt",
+                    "value": {
+                      "success": true,
+                      "email": "randomuser98765zzz@gmx.com",
+                      "validEmail": "app_server_blocked",
+                      "validSyntax": true,
+                      "reason": "We are unable to determine the validity of email at the moment. Please try later.",
+                      "domain": {
+                        "name": "gmx.com",
+                        "disposable": false,
+                        "spam": false,
+                        "free": true,
+                        "validDomain": true,
+                        "catchAll": false
+                      },
+                      "account": {
+                        "role": false
+                      },
+                      "dns": {
+                        "mxRecord": ["mx00.gmx.net."]
+                      }
+                    }
                   }
                 }
               }
@@ -205,10 +229,10 @@
                   "missingEmail": {
                     "summary": "email field missing from request body",
                     "value": {
-                      "timestamp": "2026-07-27T12:51:23.593986185Z",
-                      "path": "/v2.0/email-validation/single",
+                      "timestamp": "2026-09-02T11:56:23.462Z",
+                      "path": "/v2/email-validation/single",
                       "status": 400,
-                      "error": "External API Error",
+                      "error": "Missing or Invalid Parameters",
                       "message": "Please pass valid value for 'email' in body."
                     }
                   }
@@ -259,6 +283,38 @@
               }
             }
           },
+          "404": {
+            "description": "Not Found – The requested resource could not be found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Resource Not Found": {
+                    "value": {
+                      "timestamp": "2026-09-02T11:56:23.937Z",
+                      "path": "/v1.0/email-validation/singlex",
+                      "status": 404,
+                      "error": "Resource Not Found",
+                      "message": "The requested resource could not be found. Please verify the URL and try again."
+                    }
+                  }
+                }
+              }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              },
+              "X-Concurrent-Threads": {
+                "$ref": "#/components/headers/X-Concurrent-Threads"
+              },
+              "X-Concurrent-Threads-Active": {
+                "$ref": "#/components/headers/X-Concurrent-Threads-Active"
+              }
+            }
+          },
           "429": {
             "description": "Rate Limit Exceeded",
             "content": {
@@ -335,8 +391,8 @@
           },
           "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."
+            "enum": ["valid", "invalid", "INVALID_EMAIL", "unknown", "risky", "app_server_blocked"],
+            "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. risky is a documented possibility not observed during testing. app_server_blocked is returned when the recipient mail server blocked the live verification attempt (reason explains that retrying later may succeed)."
           },
           "validSyntax": {
             "type": "boolean",
@@ -410,16 +466,16 @@
       },
       "DnsObject": {
         "type": "object",
-        "required": ["mxRecords"],
+        "required": ["mxRecord"],
         "properties": {
-          "mxRecords": {
+          "mxRecord": {
             "type": "array",
             "items": {
               "type": "string"
             },
             "description": "Collection of MX (Mail Exchange) hostname records from DNS queries."
           },
-          "aRecords": {
+          "aRecord": {
             "type": "array",
             "items": {
               "type": "string"