{"openapi":"3.1.0","info":{"title":"WebSafely API","version":"1.0.0","summary":"Domain intelligence API","description":"Access WebSafely's domain intelligence database through a simple API.\n\nLook up stored intelligence for domains including WHOIS, DNS, IP/ASN,\nSSL, popularity, threat detection, technology, category, and risk data.\n\nIf a domain is not in the database, use `POST /v1/scan` to request a scan.\nAuthenticate with an API key using the `x-api-key` or `apikey` header.\n\nRequests are limited to 60 per minute per API key.\n","contact":{"name":"WebSafely","email":"websafelyteam@gmail.com","url":"https://websafely.app"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://websafely.app/v1"}],"tags":[{"name":"Domain Intelligence","description":"Look up stored domain intelligence."},{"name":"Scanning","description":"Request intelligence for a domain not yet in the database."},{"name":"Usage","description":"API plan and quota."}],"security":[{"apiKey":[]},{"apiKeyAlias":[]}],"paths":{"/v1/domain/{domain}":{"get":{"tags":["Domain Intelligence"],"operationId":"getDomain","summary":"Get domain intelligence","description":"Retrieve stored intelligence for a domain or subdomain from the\nWebSafely database.\n\nIf the domain has not been scanned, use `POST /v1/scan` first.\n","parameters":[{"$ref":"#/components/parameters/Domain"}],"responses":{"200":{"description":"Domain intelligence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResult"},"example":{"domain":"google.com","status":"completed","scamScore":8,"riskLevel":"Low Risk","category":"News","details":{"whois_registrar":"MarkMonitor Inc.","whois_created":"1997-09-15","whois_updated":"2024-08-02","popularity_rank":1,"threat_detection":"None","ip_country":"United States","ip":"142.251.210.142","asn":"AS15169 Google LLC","dns_a":"142.251.40.110","dns_mx":"10 smtp.google.com.","dns_txt":"v=spf1 include:_spf.google.com ~all","dns_ns":"ns3.google.com.,ns2.google.com.,ns1.google.com.,ns4.google.com.","ssl_expiry":"2026-12-03","ssl_issuer":"Google Trust Services","title":"Google","http_status_code":200,"ssl_certificate_valid":true,"ssl_certificate_type":"DV","similar_domains":"encyclopaediainfluenced.com,highjackdiscussed.com,beepergaily.com","tech_detected":"Vercel Analytics,Google Web Server,HSTS,HTTP/3,Vercel"}}}}},"400":{"$ref":"#/components/responses/InvalidDomain"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/RequestFailed"}}}},"/v1/scan":{"post":{"tags":["Scanning"],"operationId":"scanDomain","summary":"Scan a domain","description":"Request a scan for a domain and add its intelligence to the WebSafely\ndatabase. Scanning is intended for domains that are not already in the\ndatabase.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"},"example":{"url":"google.com"}}}},"responses":{"202":{"description":"Scan initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResponse"},"example":{"url":"google.com","scan_status":"initiated"}}}},"400":{"$ref":"#/components/responses/InvalidDomain"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/RequestFailed"}}}},"/v1/usage":{"get":{"tags":["Usage"],"operationId":"getUsage","summary":"Get API usage","description":"Returns the current plan and monthly quota.","responses":{"200":{"description":"Current usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"},"example":{"plan":"10k","api_status":"active","monthly_quota":10000,"current_quota":8998,"used":1002,"issued_at":"2026-09-26","period_started_at":"2026-09-26","period_ends_at":"2026-10-26"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/RequestFailed"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key issued for your account. Send it on every request."},"apiKeyAlias":{"type":"apiKey","in":"header","name":"apikey","description":"Alternate header name for the same API key."}},"parameters":{"Domain":{"name":"domain","in":"path","required":true,"description":"Domain or subdomain to look up, such as `google.com` or `mail.google.com`. A leading `www.` is ignored. The value must be a valid FQDN.","schema":{"type":"string","minLength":1,"maxLength":253,"example":"google.com"}}},"schemas":{"ScanRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Domain or URL to scan.","example":"google.com"}}},"ScanResponse":{"type":"object","required":["url","scan_status"],"properties":{"url":{"type":"string","example":"google.com"},"scan_status":{"type":"string","enum":["initiated"],"example":"initiated"}}},"DomainResult":{"type":"object","required":["domain","status","scamScore","riskLevel","category","details"],"properties":{"domain":{"type":"string","example":"google.com"},"status":{"type":"string","enum":["completed"]},"scamScore":{"type":"number","minimum":0,"maximum":100,"example":8},"riskLevel":{"type":"string","enum":["Low Risk","Uncertain","Suspicious","High Risk"],"example":"Low Risk"},"category":{"type":"string","example":"News"},"details":{"$ref":"#/components/schemas/DomainDetails"}}},"DomainDetails":{"type":"object","description":"Domain intelligence collected by WebSafely.","properties":{"whois_registrar":{"type":"string"},"whois_created":{"type":"string","format":"date"},"whois_updated":{"type":"string","format":"date"},"popularity_rank":{"type":"integer"},"threat_detection":{"type":"string"},"ip_country":{"type":"string"},"ip":{"type":"string"},"asn":{"type":"string"},"dns_a":{"type":"string"},"dns_mx":{"type":"string"},"dns_txt":{"type":"string"},"dns_ns":{"type":"string"},"ssl_expiry":{"type":"string","format":"date"},"ssl_issuer":{"type":"string"},"title":{"type":"string"},"http_status_code":{"type":"integer"},"ssl_certificate_valid":{"type":"boolean"},"ssl_certificate_type":{"type":"string"},"similar_domains":{"type":"string"},"tech_detected":{"type":"string"}}},"Usage":{"type":"object","required":["plan","api_status","monthly_quota","current_quota","used","issued_at","period_started_at","period_ends_at"],"properties":{"plan":{"type":"string","example":"10k"},"api_status":{"type":"string","example":"active"},"monthly_quota":{"type":"integer","example":10000},"current_quota":{"type":"integer","example":8998},"used":{"type":"integer","example":1002},"issued_at":{"type":"string","format":"date"},"period_started_at":{"type":"string","format":"date"},"period_ends_at":{"type":"string","format":"date"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"InvalidApiKey":{"description":"The API key is missing, unknown, or not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid":{"summary":"Invalid API key","value":{"error":{"code":"INVALID_API_KEY","message":"The API key is invalid."}}}}}}},"InvalidDomain":{"description":"The domain is missing or is not a valid FQDN.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid":{"summary":"Invalid domain","value":{"error":{"code":"INVALID_DOMAIN","message":"The supplied domain is invalid."}}}}}}},"NotFound":{"description":"No intelligence is available for this domain. This response does not use quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notScanned":{"summary":"Domain has not been scanned","value":{"error":{"code":"NOT_SCANNED","message":"Domain has not been scanned. Initiate a scan first."}}}}}}},"TooManyRequests":{"description":"The API key exceeded the monthly quota, or the 60 request per minute rate limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quota":{"summary":"Monthly quota exceeded","value":{"error":{"code":"QUOTA_EXCEEDED","message":"Monthly request quota has been exceeded."}}},"rateLimit":{"summary":"Per-minute rate limit exceeded","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please retry later."}}}}}}},"RateLimited":{"description":"More than 60 requests were sent in one minute for this API key. This response does not use quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimit":{"summary":"Per-minute rate limit exceeded","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please retry later."}}}}}}},"RequestFailed":{"description":"We faced some error, the result could not be read. Quota is not used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"failed":{"summary":"We faced some error","value":{"error":{"code":"REQUEST_FAILED","message":"The request could not be completed due to an error."}}}}}}}}}}