{
  "openapi": "3.0.0",
  "info": {
    "title": "isMalicious - Threat Intelligence API",
    "version": "1.0.0",
    "description": "Official isMalicious threat intelligence API for domain, IP, and URL reputation checking.\n\n**Base URL:** `https://api.ismalicious.com`\n\n**Documentation:** [ismalicious.com/api-docs](https://ismalicious.com/api-docs)\n\n---\n\n## Authentication\n\nGet your API keys from [ismalicious.com/app/account](https://ismalicious.com/app/account)\n\n**Header:** `X-API-KEY`\n**Value:** Base64 encode `apiKey:apiSecret`\n\n```javascript\n// Example in JavaScript\nconst apiKey = btoa(`${API_KEY}:${API_SECRET}`);\n```\n\n---\n\n## Rate Limits\n\n| Plan | Requests/min | Requests/day |\n|------|--------------|-------------|\n| FREE | 10 | 100 |\n| BASIC | 60 | 5,000 |\n| PRO | 300 | 50,000 |\n| Custom | Contact sales | Contact sales |",
    "contact": {
      "name": "isMalicious Support",
      "url": "https://ismalicious.com/support",
      "email": "support@ismalicious.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://ismalicious.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.ismalicious.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "check",
      "description": "Threat intelligence check endpoints for IPs and domains"
    },
    {
      "name": "search",
      "description": "Search for similar malicious domains"
    },
    {
      "name": "blocklist",
      "description": "Download and manage blocklists"
    },
    {
      "name": "submit",
      "description": "Submit new threat intelligence sources"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/check": {
      "get": {
        "summary": "Full Threat Analysis",
        "operationId": "checkAll",
        "tags": ["check"],
        "description": "Comprehensive threat intelligence check for IPs and domains.\n\n**Enrichment Levels:**\n- `basic` - Malicious status, reputation, geo, whois, certificates, vulnerabilities\n- `standard` - Basic + risk score, classification, confidence, MITRE mapping\n- `full` - Standard + detection timeline, related infrastructure, DNS analysis, tech stack",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "IP address or domain to check",
            "schema": {
              "type": "string"
            },
            "example": "8.8.8.8"
          },
          {
            "name": "enrichment",
            "in": "query",
            "required": false,
            "description": "Enrichment level: basic, standard, or full",
            "schema": {
              "type": "string",
              "enum": ["basic", "standard", "full"],
              "default": "standard"
            },
            "example": "standard"
          },
          {
            "name": "trackReports",
            "in": "query",
            "required": false,
            "description": "Track this check in reports history",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "Successful threat analysis response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckResponse"
                },
                "example": {
                  "malicious": false,
                  "reputation": {
                    "malicious": 0,
                    "suspicious": 0,
                    "harmless": 85,
                    "undetected": 15
                  },
                  "riskScore": {
                    "score": 5,
                    "level": "safe",
                    "factors": []
                  },
                  "confidence": {
                    "score": 95,
                    "level": "high"
                  },
                  "classification": {
                    "primary": "safe",
                    "secondary": []
                  },
                  "geo": {
                    "country": "United States",
                    "countryCode": "US",
                    "city": "Mountain View",
                    "isp": "Google LLC"
                  },
                  "apiVersion": "v2",
                  "enrichmentLevel": "standard"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests - Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/check/reputation": {
      "get": {
        "summary": "Check Reputation",
        "operationId": "checkReputation",
        "tags": ["check"],
        "description": "Get reputation data from aggregated threat intelligence sources including VirusTotal integration.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "IP address or domain",
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Reputation data response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReputationResponse"
                },
                "example": {
                  "reputation": {
                    "malicious": 0,
                    "suspicious": 2,
                    "harmless": 80,
                    "undetected": 18
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/check/location": {
      "get": {
        "summary": "Check Geolocation",
        "operationId": "checkLocation",
        "tags": ["check"],
        "description": "Get geographic location data including country, city, region, ISP, and coordinates.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "IP address or domain",
            "schema": {
              "type": "string"
            },
            "example": "1.1.1.1"
          }
        ],
        "responses": {
          "200": {
            "description": "Geolocation data response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoResponse"
                },
                "example": {
                  "geo": {
                    "country": "Australia",
                    "countryCode": "AU",
                    "city": "Sydney",
                    "region": "New South Wales",
                    "lat": -33.8688,
                    "lon": 151.2093,
                    "isp": "Cloudflare Inc"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/check/certificates": {
      "get": {
        "summary": "Check Certificates",
        "operationId": "checkCertificates",
        "tags": ["check"],
        "description": "Get SSL/TLS certificate information including issuer, validity, and chain details.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Domain or IP address",
            "schema": {
              "type": "string"
            },
            "example": "google.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Certificate data response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificatesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/check/vulnerabilities": {
      "get": {
        "summary": "Check Vulnerabilities",
        "operationId": "checkVulnerabilities",
        "tags": ["check"],
        "description": "Get known vulnerabilities associated with an IP address from CVE databases.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "IP address",
            "schema": {
              "type": "string"
            },
            "example": "192.168.1.1"
          }
        ],
        "responses": {
          "200": {
            "description": "Vulnerabilities data response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VulnerabilitiesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/check/whois": {
      "get": {
        "summary": "Check WHOIS",
        "operationId": "checkWhois",
        "tags": ["check"],
        "description": "Get WHOIS registration data including registrant, registrar, and registration dates.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "IP address or domain",
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "WHOIS data response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhoisResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/search": {
      "post": {
        "summary": "Search Keywords",
        "operationId": "searchKeywords",
        "tags": ["search"],
        "description": "Fuzzy search for similar malicious domains. Useful for finding typosquatting and phishing domains targeting a specific brand.",
        "parameters": [
          {
            "name": "keywords",
            "in": "query",
            "required": true,
            "description": "Search keywords (e.g., 'paypal', 'microsoft')",
            "schema": {
              "type": "string"
            },
            "example": "paypal"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "keywords": "paypal",
                  "hits": [
                    "paypa1-secure.com",
                    "paypal-login-verify.net",
                    "secure-paypal-update.org"
                  ],
                  "total_hits": 127
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/submit": {
      "post": {
        "summary": "Submit Sources",
        "operationId": "submitSources",
        "tags": ["submit"],
        "description": "Submit new threat intelligence sources to the community database.\n\n**Categories:** malware, phishing, spam, scam, fraud, botnet, ransomware, c2",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSourcesRequest"
              },
              "example": {
                "sources": [
                  {
                    "name": "Example Threat Feed",
                    "type": "ip",
                    "url": "https://example.com/threats-ips.txt",
                    "category": "malware"
                  },
                  {
                    "name": "Phishing Domains Feed",
                    "type": "domain",
                    "url": "https://example.com/phishing-domains.txt",
                    "category": "phishing"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Submission successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitResponse"
                },
                "example": {
                  "message": "Submitted successfully, thanks sharing new sources with us!"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/blocklist/stats": {
      "get": {
        "summary": "Get Blocklist Stats",
        "operationId": "getBlocklistStats",
        "tags": ["blocklist"],
        "description": "Get entry counts and last updated timestamps for all available blocklists.\n\n**No authentication required.**",
        "security": [],
        "responses": {
          "200": {
            "description": "Blocklist statistics response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlocklistStatsResponse"
                },
                "example": {
                  "blocklist-ips-critical.txt": {
                    "count": 15420,
                    "lastUpdated": "2024-12-28T07:00:00.000Z"
                  },
                  "blocklist-domains-phishing.txt": {
                    "count": 89234,
                    "lastUpdated": "2024-12-28T07:00:00.000Z"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/blocklist/download/{filename}": {
      "get": {
        "summary": "Download Blocklist",
        "operationId": "downloadBlocklist",
        "tags": ["blocklist"],
        "description": "Download a specific blocklist file.\n\n**Plan Access:**\n- FREE: 10% sample (lite version)\n- BASIC+: Full blocklist\n\n**Available Blocklists:**\n- `blocklist-ips-critical.txt` - Critical severity IPs\n- `blocklist-ips-all.txt` - All malicious IPs\n- `blocklist-ips-c2.txt` - C2 server IPs\n- `blocklist-ips-botnet.txt` - Botnet IPs\n- `blocklist-domains-phishing.txt` - Phishing domains\n- `blocklist-domains-malware.txt` - Malware domains\n- `blocklist-domains-ransomware.txt` - Ransomware domains\n- `blocklist-domains-all.txt` - All malicious domains",
        "parameters": [
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "description": "Blocklist filename",
            "schema": {
              "type": "string",
              "enum": [
                "blocklist-ips-critical.txt",
                "blocklist-ips-all.txt",
                "blocklist-ips-c2.txt",
                "blocklist-ips-botnet.txt",
                "blocklist-domains-phishing.txt",
                "blocklist-domains-malware.txt",
                "blocklist-domains-ransomware.txt",
                "blocklist-domains-all.txt"
              ]
            },
            "example": "blocklist-domains-phishing.txt"
          }
        ],
        "responses": {
          "200": {
            "description": "Blocklist file download",
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=\"blocklist-domains-phishing.txt\""
              },
              "X-Blocklist-Version": {
                "description": "Blocklist version (full or lite)",
                "schema": {
                  "type": "string",
                  "enum": ["full", "lite"]
                }
              },
              "X-Blocklist-Plan": {
                "description": "User's plan",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "malicious-domain1.com\nmalicious-domain2.com\nmalicious-domain3.com"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Forbidden - Plan restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Blocklist not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/bulk/check": {
      "get": {
        "summary": "Bulk check limits and usage",
        "operationId": "bulkCheckInfo",
        "tags": ["check"],
        "description": "Returns plan-specific batch limits and usage. Use **POST** `/bulk/check` to run batch lookups.",
        "responses": {
          "200": {
            "description": "Limits and documentation JSON"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "summary": "Bulk entity check",
        "operationId": "bulkCheck",
        "tags": ["check"],
        "description": "Check up to N entities per request (N depends on subscription plan). Each entity may be a domain, IP, or URL string.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkCheckRequest"
              },
              "example": {
                "entities": ["example.com", "8.8.8.8"],
                "enrichment": "full"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkCheckResponse"
                },
                "example": {
                  "success": true,
                  "total": 2,
                  "processed": 2,
                  "results": [
                    {
                      "entity": "example.com",
                      "type": "domain",
                      "isMalicious": false,
                      "confidence": 0.1,
                      "sources": 0,
                      "categories": []
                    }
                  ],
                  "processingTimeMs": 120
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Base64 encoded `apiKey:apiSecret`. Get your keys from [ismalicious.com/app/account](https://ismalicious.com/app/account)"
      }
    },
    "schemas": {
      "CheckResponse": {
        "type": "object",
        "properties": {
          "malicious": {
            "type": "boolean",
            "description": "Whether the entity is considered malicious"
          },
          "reputation": {
            "$ref": "#/components/schemas/ReputationData"
          },
          "riskScore": {
            "$ref": "#/components/schemas/RiskScore"
          },
          "confidence": {
            "$ref": "#/components/schemas/Confidence"
          },
          "classification": {
            "$ref": "#/components/schemas/Classification"
          },
          "geo": {
            "$ref": "#/components/schemas/GeoData"
          },
          "whois": {
            "$ref": "#/components/schemas/WhoisData"
          },
          "certificates": {
            "$ref": "#/components/schemas/CertificateData"
          },
          "vulnerabilities": {
            "$ref": "#/components/schemas/VulnerabilityData"
          },
          "apiVersion": {
            "type": "string",
            "description": "API version used"
          },
          "enrichmentLevel": {
            "type": "string",
            "enum": ["basic", "standard", "full"],
            "description": "Enrichment level applied"
          }
        }
      },
      "ReputationData": {
        "type": "object",
        "properties": {
          "malicious": {
            "type": "integer",
            "description": "Number of sources flagging as malicious"
          },
          "suspicious": {
            "type": "integer",
            "description": "Number of sources flagging as suspicious"
          },
          "harmless": {
            "type": "integer",
            "description": "Number of sources flagging as harmless"
          },
          "undetected": {
            "type": "integer",
            "description": "Number of sources with no detection"
          }
        }
      },
      "RiskScore": {
        "type": "object",
        "properties": {
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Risk score from 0-100"
          },
          "level": {
            "type": "string",
            "enum": ["safe", "low", "medium", "high", "critical"],
            "description": "Risk level category"
          },
          "factors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Factors contributing to the risk score"
          }
        }
      },
      "Confidence": {
        "type": "object",
        "properties": {
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Confidence score from 0-100"
          },
          "level": {
            "type": "string",
            "enum": ["low", "medium", "high"],
            "description": "Confidence level"
          }
        }
      },
      "Classification": {
        "type": "object",
        "properties": {
          "primary": {
            "type": "string",
            "description": "Primary classification"
          },
          "secondary": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Secondary classifications"
          }
        }
      },
      "GeoData": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country name"
          },
          "countryCode": {
            "type": "string",
            "description": "ISO country code"
          },
          "city": {
            "type": "string",
            "description": "City name"
          },
          "region": {
            "type": "string",
            "description": "Region or state"
          },
          "lat": {
            "type": "number",
            "description": "Latitude"
          },
          "lon": {
            "type": "number",
            "description": "Longitude"
          },
          "isp": {
            "type": "string",
            "description": "Internet Service Provider"
          }
        }
      },
      "WhoisData": {
        "type": "object",
        "properties": {
          "registrar": {
            "type": "string",
            "description": "Domain registrar"
          },
          "registrant": {
            "type": "string",
            "description": "Registrant name or organization"
          },
          "createdDate": {
            "type": "string",
            "format": "date-time",
            "description": "Domain creation date"
          },
          "updatedDate": {
            "type": "string",
            "format": "date-time",
            "description": "Last update date"
          },
          "expiresDate": {
            "type": "string",
            "format": "date-time",
            "description": "Domain expiration date"
          },
          "nameServers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Name servers"
          }
        }
      },
      "CertificateData": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string",
            "description": "Certificate issuer"
          },
          "subject": {
            "type": "string",
            "description": "Certificate subject"
          },
          "validFrom": {
            "type": "string",
            "format": "date-time",
            "description": "Certificate validity start date"
          },
          "validTo": {
            "type": "string",
            "format": "date-time",
            "description": "Certificate validity end date"
          },
          "serialNumber": {
            "type": "string",
            "description": "Certificate serial number"
          },
          "fingerprint": {
            "type": "string",
            "description": "Certificate fingerprint"
          }
        }
      },
      "VulnerabilityData": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total vulnerabilities found"
          },
          "critical": {
            "type": "integer",
            "description": "Critical severity count"
          },
          "high": {
            "type": "integer",
            "description": "High severity count"
          },
          "medium": {
            "type": "integer",
            "description": "Medium severity count"
          },
          "low": {
            "type": "integer",
            "description": "Low severity count"
          },
          "cves": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CVE"
            },
            "description": "List of CVEs"
          }
        }
      },
      "CVE": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "CVE identifier"
          },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
            "description": "Severity level"
          },
          "score": {
            "type": "number",
            "description": "CVSS score"
          },
          "description": {
            "type": "string",
            "description": "CVE description"
          }
        }
      },
      "ReputationResponse": {
        "type": "object",
        "properties": {
          "reputation": {
            "$ref": "#/components/schemas/ReputationData"
          }
        }
      },
      "GeoResponse": {
        "type": "object",
        "properties": {
          "geo": {
            "$ref": "#/components/schemas/GeoData"
          }
        }
      },
      "CertificatesResponse": {
        "type": "object",
        "properties": {
          "certificates": {
            "$ref": "#/components/schemas/CertificateData"
          }
        }
      },
      "VulnerabilitiesResponse": {
        "type": "object",
        "properties": {
          "vulnerabilities": {
            "$ref": "#/components/schemas/VulnerabilityData"
          }
        }
      },
      "WhoisResponse": {
        "type": "object",
        "properties": {
          "whois": {
            "$ref": "#/components/schemas/WhoisData"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "keywords": {
            "type": "string",
            "description": "Search keywords used"
          },
          "hits": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Matching domains"
          },
          "total_hits": {
            "type": "integer",
            "description": "Total number of matches"
          }
        }
      },
      "SubmitSourcesRequest": {
        "type": "object",
        "required": ["sources"],
        "properties": {
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreatSource"
            }
          }
        }
      },
      "ThreatSource": {
        "type": "object",
        "required": ["name", "type", "url", "category"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the threat feed"
          },
          "type": {
            "type": "string",
            "enum": ["ip", "domain"],
            "description": "Type of entities in the feed"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the threat feed"
          },
          "category": {
            "type": "string",
            "enum": ["malware", "phishing", "spam", "scam", "fraud", "botnet", "ransomware", "c2"],
            "description": "Threat category"
          }
        }
      },
      "SubmitResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Success message"
          }
        }
      },
      "BlocklistStatsResponse": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/BlocklistStat"
        }
      },
      "BlocklistStat": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of entries in the blocklist"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error type"
          },
          "message": {
            "type": "string",
            "description": "Detailed error message"
          }
        }
      },
      "BulkCheckRequest": {
        "type": "object",
        "required": ["entities"],
        "properties": {
          "entities": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Domains, IPs, and/or URLs to check"
          },
          "enrichment": {
            "type": "string",
            "description": "Optional enrichment level (e.g. basic, standard, full)"
          }
        }
      },
      "BulkEntityResult": {
        "type": "object",
        "properties": {
          "entity": { "type": "string" },
          "type": { "type": "string", "description": "domain | ip | url" },
          "isMalicious": { "type": "boolean" },
          "confidence": { "type": "number" },
          "sources": { "type": "integer" },
          "categories": {
            "type": "array",
            "items": { "type": "string" }
          },
          "error": { "type": "string" }
        }
      },
      "BulkCheckResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "total": { "type": "integer" },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/BulkEntityResult" }
          },
          "errors": {
            "type": "array",
            "items": { "type": "string" }
          },
          "processingTimeMs": { "type": "integer" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - Invalid parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Bad Request",
              "message": "Missing required parameter: query"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Unauthorized",
              "message": "Invalid or missing API key"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests - Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Rate Limited",
              "message": "You have exceeded your rate limit. Please try again later."
            }
          }
        }
      }
    }
  }
}