@apifreaks/openapi-specs 0.1.0

package/specs/ip-intelligence/ip-threat-intelligence.json

@@ -0,0 +1,316 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "IP Threat Intelligence API - VPN, Proxy & Tor Detection with Threat Scoring",
+    "version": "1.0.0",
+    "description": "Retrieve real-time threat intelligence and security signals for a single IPv4 or IPv6 address. Returns an aggregate `threat_score` (0-100) plus detection flags and provider names for VPNs, proxies (including residential proxies), Tor exit nodes, relays, known attackers, bots, spam sources, and cloud-provider ranges. Use `fields`/`excludes` with dot notation (e.g. `security.threat_score`) to trim the response to only the modules you need. If `ip` is omitted, the API returns threat data for the public IP of the requesting client. Bogon and reserved IP addresses return a `423` error, and malformed IP input returns a `400` error, instead of partial data.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "IP Threat Intelligence API Server"
+    }
+  ],
+  "paths": {
+    "/ip/security": {
+      "get": {
+        "tags": ["IP Geolocation APIs"],
+        "summary": "Retrieve real-time threat intelligence and security signals for an IPv4 or IPv6 address",
+        "description": "Get a threat score along with VPN, proxy, Tor, relay, bot, spam, known-attacker, and cloud-provider detection flags for an IP address.",
+        "operationId": "ipSecurityLookup",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "ip",
+            "in": "query",
+            "required": false,
+            "description": "IPv4 or IPv6 address to check for threat intelligence and security signals. If omitted, the public IP of the requesting client is used.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "fields",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated list of fields to return. Supports dot notation (e.g. `security.threat_score`).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "excludes",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated list of fields to remove from the response. Supports dot notation (e.g. `security.is_tor`). The `ip` field is always included and cannot be excluded.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful threat intelligence response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/IpSecurityResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "ip": "8.8.8.8",
+                      "security": {
+                        "threat_score": 5,
+                        "is_tor": false,
+                        "is_proxy": false,
+                        "proxy_provider_names": [],
+                        "proxy_confidence_score": 0,
+                        "proxy_last_seen": "",
+                        "is_residential_proxy": false,
+                        "is_vpn": false,
+                        "vpn_provider_names": [],
+                        "vpn_confidence_score": 0,
+                        "vpn_last_seen": "",
+                        "is_relay": false,
+                        "relay_provider_name": "",
+                        "is_anonymous": false,
+                        "is_known_attacker": false,
+                        "is_bot": false,
+                        "is_spam": false,
+                        "is_cloud_provider": true,
+                        "cloud_provider_name": "Google LLC"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Invalid or missing IP address",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "invalidIp": {
+                    "summary": "Malformed IP address",
+                    "value": {
+                      "message": "Provided IP address 'invalid' is not valid"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "423": {
+            "description": "Locked — Bogon or reserved IP address",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "locked": {
+                    "summary": "Bogon or reserved IP address",
+                    "value": {
+                      "message": "'10.0.0.1' is a bogon IP address."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "ErrorResponse": {
+        "type": "object",
+        "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)."
+          }
+        }
+      },
+      "IpSecurityResponse": {
+        "type": "object",
+        "description": "Threat intelligence result for an IP address.",
+        "required": ["ip"],
+        "properties": {
+          "ip": {
+            "type": "string",
+            "description": "The IP address used for the lookup (IPv4 or IPv6)."
+          },
+          "security": {
+            "$ref": "#/components/schemas/Security"
+          }
+        }
+      },
+      "Security": {
+        "type": "object",
+        "description": "Threat intelligence and security information for the IP.",
+        "required": [
+          "threat_score",
+          "is_tor",
+          "is_proxy",
+          "proxy_confidence_score",
+          "is_residential_proxy",
+          "is_vpn",
+          "vpn_confidence_score",
+          "is_relay",
+          "is_anonymous",
+          "is_known_attacker",
+          "is_bot",
+          "is_spam",
+          "is_cloud_provider"
+        ],
+        "properties": {
+          "threat_score": {
+            "type": "number",
+            "description": "Aggregate risk score from 0 to 100."
+          },
+          "is_tor": {
+            "type": "boolean",
+            "description": "true if the IP matches a Tor exit node."
+          },
+          "is_proxy": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a proxy service."
+          },
+          "proxy_provider_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Detected proxy provider names."
+          },
+          "proxy_confidence_score": {
+            "type": "number",
+            "description": "Proxy detection confidence from 0 to 100."
+          },
+          "proxy_last_seen": {
+            "type": "string",
+            "description": "Last observed proxy activity date in YYYY-MM-DD."
+          },
+          "is_residential_proxy": {
+            "type": "boolean",
+            "description": "true if the IP is linked to a residential proxy network."
+          },
+          "is_vpn": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a VPN service."
+          },
+          "vpn_provider_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Detected VPN provider names."
+          },
+          "vpn_confidence_score": {
+            "type": "number",
+            "description": "VPN detection confidence from 0 to 100."
+          },
+          "vpn_last_seen": {
+            "type": "string",
+            "description": "Last observed VPN activity date in YYYY-MM-DD."
+          },
+          "is_relay": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a relay network."
+          },
+          "relay_provider_name": {
+            "type": "string",
+            "description": "Relay provider name."
+          },
+          "is_anonymous": {
+            "type": "boolean",
+            "description": "true if any anonymity signal is present."
+          },
+          "is_known_attacker": {
+            "type": "boolean",
+            "description": "true if the IP is flagged for known attacker behavior."
+          },
+          "is_bot": {
+            "type": "boolean",
+            "description": "true if the IP is associated with bot activity."
+          },
+          "is_spam": {
+            "type": "boolean",
+            "description": "true if the IP is associated with spam activity."
+          },
+          "is_cloud_provider": {
+            "type": "boolean",
+            "description": "true if the IP belongs to a cloud provider range."
+          },
+          "cloud_provider_name": {
+            "type": "string",
+            "description": "Cloud provider name."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}