{ "openapi": "3.1.0", "info": { "title": "IP Reputation Checker API", "version": "v0.0.2", "description": "Screen IPs and domains for abuse signals with reputation, geolocation/ASN, DNS enrichment and batch/CIDR scans.", "x-pricing-model": "payg", "x-free-tier-calls": 0, "x-docs-url": "", "x-dakidarts-contract-status": "published", "x-dakidarts-execution-status": "source-only" }, "servers": [ { "url": "https://api.dakidarts.com/ip-reputation-checker", "description": "Dakidarts direct gateway" } ], "tags": [ { "name": "Analysis", "description": "Analysis endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Ipinfo", "description": "Ipinfo endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Operations", "description": "Operations endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Reports", "description": "Reports endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Report", "description": "Report endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Categories", "description": "Categories endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Batch operations", "description": "Batch operations endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Stats", "description": "Stats endpoints sourced from the IP Reputation Checker API implementation." }, { "name": "Cache", "description": "Cache endpoints sourced from the IP Reputation Checker API implementation." } ], "paths": { "/domain/{domain_raw}": { "get": { "summary": "Domain Scan", "description": "Resolve a domain to all its IP addresses and scan the reputation of every one. Accepts bare domains, subdomains, or full URLs.", "operationId": "ip-reputation-checker_get_domain_{domain_raw}", "tags": [ "Analysis" ], "parameters": [ { "name": "domain_raw", "in": "path", "required": true, "description": "Domain name supplied in the URL path.", "schema": { "type": "string", "example": "example.com" }, "example": "example.com" }, { "name": "max_age", "in": "query", "required": false, "description": "AbuseIPDB look-back window in days (1\u2013365).", "schema": { "type": "integer", "default": 90 } }, { "name": "force_refresh", "in": "query", "required": false, "description": "Bypass the cache and query AbuseIPDB live.", "schema": { "type": "boolean", "default": false } }, { "name": "include_reports", "in": "query", "required": false, "description": "Include the full abuse report list in the result.", "schema": { "type": "boolean", "default": false } }, { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Domain Scan", "description": "Resolve a domain to all its IP addresses and scan the reputation of every one. Accepts bare domains, subdomains, or full URLs.", "operationId": "ip-reputation-checker_post_domain_{domain_raw}", "tags": [ "Analysis" ], "parameters": [ { "name": "domain_raw", "in": "path", "required": true, "description": "Domain name supplied in the URL path.", "schema": { "type": "string", "example": "example.com" }, "example": "example.com" }, { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_age": { "type": "integer", "default": 90 }, "force_refresh": { "type": "boolean", "default": false }, "include_reports": { "type": "boolean", "default": false } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/ipinfo": { "get": { "summary": "Ipinfo", "description": "Get rich geolocation and network intel for an IP: continent, country, region, city, coordinates, flag, organization, ISP, ASN, and timezone.", "operationId": "ip-reputation-checker_get_ipinfo", "tags": [ "Ipinfo" ], "parameters": [ { "name": "ip", "in": "query", "required": true, "description": "IPv4 or IPv6 address to enrich with geolocation and ASN data.", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Ipinfo", "description": "Get rich geolocation and network intel for an IP: continent, country, region, city, coordinates, flag, organization, ISP, ASN, and timezone.", "operationId": "ip-reputation-checker_post_ipinfo", "tags": [ "Ipinfo" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "geo": { "ip": "8.8.8.8", "asn": 15169, "isp": "Google LLC", "org": "Google LLC", "city": "Mountain View", "type": "IPv4", "domain": "google.com", "region": "California", "country": "United States", "latitude": 37.4056, "timezone": "America/Los_Angeles", "continent": "North America", "longitude": -122.0775, "flag_emoji": "\ud83c\uddfa\ud83c\uddf8", "country_code": "US" }, "input": "8.8.8.8", "cached": true }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/ipinfo", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 312.7 }, "success": true } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8" } }, "required": [ "ip" ] } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "data": { "geo": { "ip": "8.8.8.8", "asn": 15169, "isp": "Google LLC", "org": "Google LLC", "city": "Mountain View", "type": "IPv4", "domain": "google.com", "region": "California", "country": "United States", "latitude": 37.4056, "timezone": "America/Los_Angeles", "continent": "North America", "longitude": -122.0775, "flag_emoji": "\ud83c\uddfa\ud83c\uddf8", "country_code": "US" }, "input": "8.8.8.8", "cached": true }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/ipinfo", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 312.7 }, "success": true } } }, "/status": { "get": { "summary": "Status", "description": "Check service health, API version, and uptime.", "operationId": "ip-reputation-checker_get_status", "tags": [ "Operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "status": "online", "version": "v0.0.2", "database": "ok", "uptime_human": "1d 0h 0m", "uptime_seconds": 86400 }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/status", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 1.2 }, "success": true } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "data": { "status": "online", "version": "v0.0.2", "database": "ok", "uptime_human": "1d 0h 0m", "uptime_seconds": 86400 }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/status", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 1.2 }, "success": true } }, "post": { "summary": "Status", "description": "Check service health, API version, and uptime.", "operationId": "ip-reputation-checker_post_status", "tags": [ "Operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/reports": { "get": { "summary": "Reports", "description": "Fetch the complete abuse report history for an IP, including report date, comment, abuse categories, and reporter details.", "operationId": "ip-reputation-checker_get_reports", "tags": [ "Reports" ], "parameters": [ { "name": "ip", "in": "query", "required": true, "description": "IPv4 or IPv6 address whose abuse-report history is requested.", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" }, { "name": "max_age", "in": "query", "required": false, "description": "AbuseIPDB look-back window in days (1\u2013365).", "schema": { "type": "integer", "default": 90 } }, { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Reports", "description": "Fetch the complete abuse report history for an IP, including report date, comment, abuse categories, and reporter details.", "operationId": "ip-reputation-checker_post_reports", "tags": [ "Reports" ], "parameters": [ { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "input": "118.25.6.39", "reports": [ { "comment": "SSH brute force attempt", "categories": [ 18, 22 ], "reported_at": "2023-07-10T20:55:14+00:00", "reporter_id": 1, "reporter_country_code": "US", "reporter_country_name": "United States" } ], "total_reports": 48 }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/reports", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 410.9 }, "success": true } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8" }, "max_age": { "type": "integer", "default": 90 } }, "required": [ "ip" ] } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "data": { "input": "118.25.6.39", "reports": [ { "comment": "SSH brute force attempt", "categories": [ 18, 22 ], "reported_at": "2023-07-10T20:55:14+00:00", "reporter_id": 1, "reporter_country_code": "US", "reporter_country_name": "United States" } ], "total_reports": 48 }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/reports", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 410.9 }, "success": true } } }, "/report": { "post": { "summary": "Report", "description": "Submit an abuse report for an IP to AbuseIPDB. Requires a key with reporting permission (your own via BYOK, or the server key).", "operationId": "ip-reputation-checker_post_report", "tags": [ "Report" ], "parameters": [ { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string" }, "categories": { "type": "array", "items": { "type": "integer" } }, "comment": { "type": "string" } }, "required": [ "categories", "ip" ] } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/categories": { "get": { "summary": "Categories", "description": "Get the full AbuseIPDB abuse category reference (IDs 1\u201323) with names and descriptions. Use these IDs with the `/report` endpoint and to interpret `reports[].categories`.", "operationId": "ip-reputation-checker_get_categories", "tags": [ "Categories" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "count": 23, "categories": [ { "id": 1, "name": "DNS Compromise", "description": "Abuse was involved in DNS cache poisoning, DNS DDoS, or DNS hijacking." }, { "id": 4, "name": "DDoS Attack", "description": "Abuse was involved in distributed denial of service attacks." }, { "id": 7, "name": "Phishing", "description": "Abuse was involved in phishing." } ] }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/categories", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 5.0 }, "success": true } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "data": { "count": 23, "categories": [ { "id": 1, "name": "DNS Compromise", "description": "Abuse was involved in DNS cache poisoning, DNS DDoS, or DNS hijacking." }, { "id": 4, "name": "DDoS Attack", "description": "Abuse was involved in distributed denial of service attacks." }, { "id": 7, "name": "Phishing", "description": "Abuse was involved in phishing." } ] }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/categories", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 5.0 }, "success": true } } }, "/scan": { "get": { "summary": "Scan", "description": "Analyze an IP address for reputation, abuse history, and risk score. Results are cached for 24 hours for fast repeat lookups.", "operationId": "ip-reputation-checker_get_scan", "tags": [ "Analysis" ], "parameters": [ { "name": "max_age", "in": "query", "required": false, "description": "Look-back window in days (1\u2013365) for AbuseIPDB", "schema": { "type": "integer", "default": 90 } }, { "name": "force_refresh", "in": "query", "required": false, "description": "Bypass the cache and hit AbuseIPDB live", "schema": { "type": "boolean", "default": false } }, { "name": "include_reports", "in": "query", "required": false, "description": "Include the full abuse report list", "schema": { "type": "boolean", "default": false } }, { "name": "geo", "in": "query", "required": false, "description": "Attach geolocation/ASN data to the analysis", "schema": { "type": "boolean", "default": false } }, { "name": "ip", "in": "query", "required": true, "description": "IPv4 or IPv6 address to check against AbuseIPDB.", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" }, { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Scan", "description": "Analyze an IP address for reputation, abuse history, and risk score. Results are cached for 24 hours for fast repeat lookups.", "operationId": "ip-reputation-checker_post_scan", "tags": [ "Analysis" ], "parameters": [ { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_age": { "type": "integer", "default": 90 }, "force_refresh": { "type": "boolean", "default": false }, "include_reports": { "type": "boolean", "default": false }, "geo": { "type": "boolean", "default": false }, "ip": { "type": "string", "example": "8.8.8.8" } }, "required": [ "ip" ] } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/scan/me": { "get": { "summary": "Scan Me", "description": "Analyze the caller's own IP address \u2014 no parameters needed.", "operationId": "ip-reputation-checker_get_scan_me", "tags": [ "Analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Scan Me", "description": "Analyze the caller's own IP address \u2014 no parameters needed.", "operationId": "ip-reputation-checker_post_scan_me", "tags": [ "Analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/scan/batch": { "post": { "summary": "Scan Batch", "description": "Scan up to 20 IP addresses in a single request. Each IP is evaluated independently \u2014 one bad address won't fail the whole batch.", "operationId": "ip-reputation-checker_post_scan_batch", "tags": [ "Batch operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" } }, "max_age": { "type": "integer", "default": 90 }, "force_refresh": { "type": "boolean", "default": false }, "include_reports": { "type": "boolean", "default": false }, "geo": { "type": "boolean", "default": false } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/scan/bulk": { "post": { "summary": "Scan Bulk", "description": "Scan a whole CIDR block (e.g. `8.8.8.0/24`) or a list of up to 40 IPs. Provide exactly one of `network` or `ips`.", "operationId": "ip-reputation-checker_post_scan_bulk", "tags": [ "Batch operations" ], "parameters": [ { "name": "X-AbuseIPDB-Key", "in": "header", "required": false, "description": "Optional AbuseIPDB API key for BYOK; otherwise the configured server key is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "network": "8.8.8.0/24", "max_address": "8.8.8.255", "min_address": "8.8.8.0", "total_reports": 7, "reported_count": 2, "num_distinct_users": 3, "num_possible_hosts": 256, "reported_addresses": [ { "ip": "8.8.8.2", "num_reports": 5, "country_code": "US", "last_reported_at": "2026-08-10T12:00:00Z", "most_recent_report": "2026-08-10T12:00:00Z", "abuse_confidence_score": 100 } ] }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/scan/bulk", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 800.2 }, "success": true } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "x-required-group": "network-or-ips" }, "ips": { "type": "array", "items": { "type": "string" }, "x-required-group": "network-or-ips" }, "max_age": { "type": "integer" }, "force_refresh": { "type": "boolean", "default": false } } } } } }, "x-required-groups": { "network-or-ips": [ "network", "ips" ] }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "data": { "network": "8.8.8.0/24", "max_address": "8.8.8.255", "min_address": "8.8.8.0", "total_reports": 7, "reported_count": 2, "num_distinct_users": 3, "num_possible_hosts": 256, "reported_addresses": [ { "ip": "8.8.8.2", "num_reports": 5, "country_code": "US", "last_reported_at": "2026-08-10T12:00:00Z", "most_recent_report": "2026-08-10T12:00:00Z", "abuse_confidence_score": 100 } ] }, "meta": { "api": "IP Reputation Checker", "version": "v0.0.2", "endpoint": "/scan/bulk", "timestamp": "2026-08-28T10:00:00Z", "latency_ms": 800.2 }, "success": true } } }, "/stats": { "get": { "summary": "Stats", "description": "Usage analytics derived from the scan log (last 90 days by default).", "operationId": "ip-reputation-checker_get_stats", "tags": [ "Stats" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/cache": { "get": { "summary": "Cache", "description": "Cache statistics (reputation + geo caches, TTLs, most-requested entries).", "operationId": "ip-reputation-checker_get_cache", "tags": [ "Cache" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "security": [ { "ApiKeyAuth": [] } ] }