@apifreaks/openapi-specs 0.2.0 → 0.3.1

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.",
@@ -100,6 +100,17 @@
                   }
                 }
               }
+            },
+            "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": {
@@ -122,6 +133,63 @@
                   }
                 }
               }
+            },
+            "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"
+              }
+            }
+          },
+          "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": {
@@ -143,6 +211,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           },
           "429": {
@@ -164,6 +237,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           }
         },
@@ -190,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": {
@@ -224,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",
@@ -299,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"
@@ -464,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"
             }
@@ -521,6 +606,26 @@
           }
         }
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "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": [

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,9 +178,44 @@
                         }
                       }
                     }
+                  },
+                  "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"
+              },
+              "X-Concurrent-Threads": {
+                "$ref": "#/components/headers/X-Concurrent-Threads"
+              },
+              "X-Concurrent-Threads-Active": {
+                "$ref": "#/components/headers/X-Concurrent-Threads-Active"
+              }
             }
           },
           "400": {
@@ -194,15 +229,26 @@
                   "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": {
+                "$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": {
@@ -224,6 +270,49 @@
                   }
                 }
               }
+            },
+            "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"
+              }
+            }
+          },
+          "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": {
@@ -245,6 +334,17 @@
                   }
                 }
               }
+            },
+            "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"
+              }
             }
           }
         },
@@ -291,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",
@@ -366,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"
@@ -573,6 +673,26 @@
           }
         }
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "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": [

package/specs/financial/bulk-vat-rates-country.json

@@ -116,6 +116,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           },
           "400": {
@@ -138,6 +143,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           },
           "413": {
@@ -160,6 +170,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           }
         }
@@ -328,6 +343,14 @@
           }
         }
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "description": "Specifies the number of credits consumed by the current request.",
+        "schema": {
+          "type": "integer"
+        }
+      }
     }
   },
   "security": [

package/specs/financial/financial-apis-supported-countries.json

@@ -58,7 +58,11 @@
                     "summary": "Typical successful response (truncated)",
                     "value": {
                       "VAT_Supported_Countries_And_States": [
-                        { "germany": { "code": "de" } },
+                        {
+                          "germany": {
+                            "code": "de"
+                          }
+                        },
                         {
                           "united_states": {
                             "code": "us",
@@ -71,17 +75,34 @@
                         }
                       ],
                       "IBAN_Supported_Countries": [
-                        { "countryCode": "DE", "name": "Germany" },
-                        { "countryCode": "GB", "name": "United Kingdom" }
+                        {
+                          "countryCode": "DE",
+                          "name": "Germany"
+                        },
+                        {
+                          "countryCode": "GB",
+                          "name": "United Kingdom"
+                        }
                       ],
                       "SWIFT_Supported_Countries": [
-                        { "name": "Germany", "countryCode": "DE" },
-                        { "name": "United States", "countryCode": "US" }
+                        {
+                          "name": "Germany",
+                          "countryCode": "DE"
+                        },
+                        {
+                          "name": "United States",
+                          "countryCode": "US"
+                        }
                       ]
                     }
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           }
         }
@@ -191,6 +212,14 @@
           }
         }
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "description": "Specifies the number of credits consumed by the current request.",
+        "schema": {
+          "type": "integer"
+        }
+      }
     }
   },
   "security": [

package/specs/financial/iban-validation.json

@@ -136,6 +136,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           },
           "400": {
@@ -158,6 +163,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           }
         },
@@ -315,6 +325,14 @@
         },
         "description": "Standard error envelope returned by the API on failed requests."
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "description": "Specifies the number of credits consumed by the current request.",
+        "schema": {
+          "type": "integer"
+        }
+      }
     }
   },
   "security": [

package/specs/financial/swift-code-finder.json

@@ -74,7 +74,13 @@
                 "examples": {
                   "allCountries": {
                     "summary": "No parameters — all supported countries",
-                    "value": ["Albania", "Algeria", "Andorra", "Germany", "United States"]
+                    "value": [
+                      "Albania",
+                      "Algeria",
+                      "Andorra",
+                      "Germany",
+                      "United States"
+                    ]
                   },
                   "banksInCountry": {
                     "summary": "country only — bank names in that country",
@@ -82,7 +88,12 @@
                   },
                   "citiesForBank": {
                     "summary": "country + bank — cities that bank operates in",
-                    "value": ["AACHEN", "BERLIN", "FRANKFURT AM MAIN", "MUENCHEN"]
+                    "value": [
+                      "AACHEN",
+                      "BERLIN",
+                      "FRANKFURT AM MAIN",
+                      "MUENCHEN"
+                    ]
                   },
                   "swiftCodes": {
                     "summary": "country + bank + city — matching SWIFT/BIC codes",
@@ -100,6 +111,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           },
           "400": {
@@ -118,6 +134,11 @@
                   }
                 }
               }
+            },
+            "headers": {
+              "X-AF-Credits-Cost": {
+                "$ref": "#/components/headers/X-AF-Credits-Cost"
+              }
             }
           }
         }
@@ -179,6 +200,14 @@
           }
         }
       }
+    },
+    "headers": {
+      "X-AF-Credits-Cost": {
+        "description": "Specifies the number of credits consumed by the current request.",
+        "schema": {
+          "type": "integer"
+        }
+      }
     }
   },
   "security": [