IP Intelligence API

Real-time IP threat scoring, geolocation, and network intelligence.

Authentication: WAYSCloud API key via X-API-Key header. Free tier auto-provisioned on first use — no manual activation needed.

Free tier: 1,000 requests/day. Upgrade via dashboard.

Endpoint	Description
`GET /v1/ip/{ip}`	Full summary (geo + network + threat + flags)
`GET /v1/ip/{ip}/geo`	Geolocation + rDNS + ASN
`GET /v1/ip/{ip}/threat`	Threat score + categories + flags
`GET /v1/ip/threats/live`	Live threat feed
`GET /v1/ip/countries/{code}`	Country intelligence
`GET /v1/ip/asn/{asn}`	ASN intelligence
`POST /v1/ip/report`	Submit IP abuse report
`POST /v1/ip/reporters/register`	Register as abuse reporter
`POST /v1/ip/reporters/verify`	Verify reporter domain (DNS TXT)
`POST /v1/ip/delist`	Request IP delisting

Docs: docs.wayscloud.services/api/ip-intelligencePortal: ip.wayscloud.services

Endpoints

Method	Path	Description
`GET`	`/v1/ip/{ip}`	IP summary
`GET`	`/v1/ip/{ip}/geo`	IP geolocation
`GET`	`/v1/ip/{ip}/threat`	IP threat assessment
`GET`	`/v1/ip/threats/live`	Live threat feed
`GET`	`/v1/ip/countries/{code}`	Country intelligence
`GET`	`/v1/ip/asn/{asn}`	ASN intelligence
`POST`	`/v1/ip/report`	Submit IP abuse report
`POST`	`/v1/ip/reporters/register`	Register as abuse reporter
`POST`	`/v1/ip/reporters/verify`	Verify reporter domain ownership
`POST`	`/v1/ip/delist`	Request IP delisting

GET /v1/ip/

IP summary

Returns geolocation, network identity, threat assessment, and detection flags for an IP address. Free tier auto-provisioned on first use.

Response:

Field	Type	Description
`ip`	`string`	Queried IP address
`ip_version`	`integer`	IP protocol version Values: `4`, `6`
`hostname`	`string`	Reverse DNS hostname (null if no rDNS record)
`geo`	`object`	Geolocation data
`network`	`object`	Network identity
`threat`	`object`	Threat assessment
`flags`	`object`	Detection flags

Example:

bash

curl https://api.wayscloud.services/v1/ip/{ip} \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "ip": "8.8.8.8",
  "ip_version": 4,
  "hostname": "dns.google",
  "geo": {
    "country": "US",
    "country_name": "United States",
    "city": "Mountain View",
    "region": "California",
    "latitude": 37.386,
    "longitude": -122.0838,
    "timezone": "America/Los_Angeles"
  },
  "network": {
    "asn": 15169,
    "isp": "Google LLC",
    "org": "Google LLC",
    "connection_type": "datacenter"
  },
  "threat": {
    "score": 0,
    "level": "clean",
    "is_clean": true
  },
  "flags": {
    "vpn": false,
    "proxy": false,
    "tor": false,
    "datacenter": true,
    "botnet": false
  }
}

GET /v1/ip/{ip}/geo

IP geolocation

Returns geolocation, reverse DNS, and ASN information.

Response:

Field	Type	Description
`ip`	`string`	Queried IP address
`ip_version`	`integer`	IP protocol version (4 or 6)
`hostname`	`string`	Reverse DNS hostname (null if no rDNS)
`country`	`string`	ISO 3166-1 alpha-2 country code
`country_name`	`string`	Human-readable country name
`city`	`string`	City name
`region`	`string`	Region or state
`latitude`	`number`	Latitude coordinate
`longitude`	`number`	Longitude coordinate
`timezone`	`string`	IANA timezone identifier
`asn`	`integer`	Autonomous System Number
`isp`	`string`	Internet Service Provider
`org`	`string`	Organization name
`connection_type`	`string`	Connection classification Values: `residential`, `mobile`, `business`, `datacenter`, `hosting`, `education`, `government`, `unknown`

Example:

bash

curl https://api.wayscloud.services/v1/ip/{ip}/geo \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "ip": "8.8.8.8",
  "ip_version": 4,
  "hostname": "dns.google",
  "country": "US",
  "country_name": "United States",
  "city": "Mountain View",
  "region": "California",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "asn": 15169,
  "isp": "Google LLC",
  "org": "Google LLC",
  "connection_type": "datacenter"
}

GET /v1/ip/{ip}/threat

IP threat assessment

Returns threat score, level, categories, and detection flags.

Response:

Field	Type	Description
`ip`	`string`	Queried IP address
`score`	`number`	Threat score (0 = clean, 100 = critical)
`level`	`string`	Human-readable threat level derived from score Values: `clean`, `low`, `medium`, `high`, `critical`
`is_clean`	`boolean`	True if no known threat reports
`total_reports`	`integer`	Number of abuse reports from all sources
`categories`	`array`	Abuse categories (e.g. brute-force, port-scan, spam). Null if clean
`first_seen`	`string`	ISO 8601 timestamp of first abuse report
`last_seen`	`string`	ISO 8601 timestamp of most recent report
`flags`	`object`	Detection flags

Example:

bash

curl https://api.wayscloud.services/v1/ip/{ip}/threat \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "ip": "203.0.113.50",
  "score": 75,
  "level": "high",
  "is_clean": false,
  "total_reports": 42,
  "categories": [
    "brute-force",
    "port-scan"
  ],
  "first_seen": "2025-11-01T08:00:00Z",
  "last_seen": "2026-03-29T14:22:00Z",
  "flags": {
    "vpn": false,
    "proxy": true,
    "tor": false,
    "datacenter": true
  }
}

GET /v1/ip/threats/live

Live threat feed

Returns the most recently reported threat IPs.

Response:

Field	Type	Description
`updated_at`	`string`	ISO 8601 timestamp of feed generation
`count`	`integer`	Number of threat entries returned
`threats`	`array`	List of recently reported threat IPs

Example:

bash

curl https://api.wayscloud.services/v1/ip/threats/live \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "updated_at": "2026-03-30T08:00:00Z",
  "count": 3,
  "threats": [
    {
      "ip": "203.0.113.50",
      "score": 85,
      "level": "high",
      "categories": [
        "brute-force"
      ],
      "country": "CN",
      "last_seen": "2026-03-30T07:55:00Z"
    },
    {
      "ip": "198.51.100.22",
      "score": 60,
      "level": "medium",
      "categories": [
        "port-scan"
      ],
      "country": "RU",
      "last_seen": "2026-03-30T07:50:00Z"
    },
    {
      "ip": "192.0.2.99",
      "score": 45,
      "level": "medium",
      "categories": [
        "spam"
      ],
      "country": "BR",
      "last_seen": "2026-03-30T07:48:00Z"
    }
  ]
}

GET /v1/ip/countries/

Country intelligence

Returns threat intelligence summary for a country.

Response:

Field	Type	Description
`country`	`string`	ISO 3166-1 alpha-2 country code
`country_name`	`string`	Human-readable country name
`total_threats`	`integer`	Total abuse reports originating from this country
`threat_density`	`number`	Reports per unique IP (higher = more concentrated abuse)
`top_categories`	`array`	Most common abuse categories from this country

Example:

bash

curl https://api.wayscloud.services/v1/ip/countries/{code} \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "country": "NO",
  "country_name": "Norway",
  "total_threats": 127,
  "threat_density": 0.003,
  "top_categories": [
    "brute-force",
    "port-scan",
    "spam"
  ]
}

GET /v1/ip/asn/

ASN intelligence

Returns threat intelligence summary for an Autonomous System.

Response:

Field	Type	Description
`asn`	`integer`	Autonomous System Number
`name`	`string`	AS name (e.g. Google LLC)
`total_ips`	`integer`	Unique IPs observed in this AS
`threat_count`	`integer`	Total abuse reports from this AS
`threat_ratio`	`number`	Reports per unique IP (abuse concentration)
`country`	`string`	Top country by report count

Example:

bash

curl https://api.wayscloud.services/v1/ip/asn/{asn} \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET"

Response:

json

{
  "asn": 15169,
  "name": "Google LLC",
  "total_ips": 4200000,
  "threat_count": 89,
  "threat_ratio": 2e-05,
  "country": "US"
}

POST /v1/ip/report

Submit IP abuse report

Report an abusive IP address to the WAYSCloud threat intelligence network.

Requires prior reporter registration via POST /v1/ip/reporters/register. Your WAYSCloud API key is used for authentication — the upstream reporter token is managed transparently.

Use cases: fail2ban integration, honeypot data, IDS alerts, manual incident reports.

Rate limiting: Reports count against your daily quota. Duplicate reports (same IP + category within 1 hour) are deduplicated.

Request Body:

Field	Type	Description
`ip`	`string`	Required. IPv4 or IPv6 address to report as abusive
`category`	`string`	Required. Abuse category. Use descriptive names — categories are automatically normalized. Common values: ssh_bruteforce, port_scan, http_flood, sip_attack, rdp_bruteforce, web_attack, spam, phishing
`severity`	`string`	Threat severity level. Affects how quickly the IP is flagged in the threat intelligence network Values: `low`, `medium`, `high`, `critical`
`confidence`	`number`	How confident you are in this report (0.0 = uncertain, 1.0 = verified). Lower confidence reduces the impact on threat scoring
`comment`	`string`	Free-text context about the abuse (e.g. "Repeated SSH login attempts from this IP over 24h")
`session_id`	`string`	Unique session identifier for deduplication across retries. Format: tool-component-timestamp-unique (e.g. fail2ban-ssh-20260330-157180)

Example:

json

{
  "ip": "45.155.205.233",
  "category": "ssh_bruteforce",
  "severity": "high",
  "confidence": 0.9,
  "comment": "Repeated SSH login attempts over 24h",
  "session_id": "fail2ban-ssh-20260330-45155205233"
}

Response:

Field	Type	Description
`report_id`	`integer`	Unique numeric report identifier
`oid_record`	`string`	Norwegian NKOM Object Identifier for this report record
`ip`	`string`	The reported IP address
`category`	`string`	Normalized abuse category
`initial_score`	`number`	Initial threat score assigned to the IP based on this report
`message`	`string`	Human-readable status message

Example:

bash

curl -X POST https://api.wayscloud.services/v1/ip/report \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "ip": "45.155.205.233",
  "category": "ssh_bruteforce",
  "severity": "high",
  "confidence": 0.9,
  "comment": "Repeated SSH login attempts over 24h",
  "session_id": "fail2ban-ssh-20260330-45155205233"
}'

Response:

json

{
  "report_id": 12345,
  "oid_record": "2.16.578.1.62.report.20260330.157180311156",
  "ip": "157.180.31.156",
  "category": "ssh_bruteforce",
  "initial_score": 24.0,
  "message": "Abuse report submitted successfully"
}

POST /v1/ip/reporters/register

Register as abuse reporter

After registration, use POST /v1/ip/report to submit abuse reports using your regular WAYSCloud API key.

Trust scores affect how much weight your reports carry:

automated (0.4): Fully automated systems like fail2ban or IDS
hybrid (0.6): Automated detection with human verification
manual (0.8): Human-verified reports
Verified domain (1.0): After DNS TXT verification via POST /v1/ip/reporters/verify

Each WAYSCloud customer can have one active reporter registration.

Request Body:

Field	Type	Description
`name`	`string`	Required. Name of your service or organization (e.g. "ACME Mail Server", "Security Research Lab")
`source_type`	`string`	Reporter type — determines initial trust score. automated=fail2ban/IDS, manual=human review, hybrid=automated+human Values: `automated`, `manual`, `hybrid`
`contact`	`string`	Contact email for verification and support communication
`intent`	`string`	What you plan to report (e.g. "fail2ban SSH bruteforce", "honeypot data", "manual security analysis")
`domain`	`string`	Your domain for ownership verification. Add DNS TXT record later to increase trust score to 1.0

Example:

json

{
  "name": "ACME Security Lab",
  "source_type": "hybrid",
  "contact": "security@acme.com",
  "intent": "fail2ban + manual incident review",
  "domain": "acme.com"
}

Response:

Field	Type	Description
`reporter_id`	`string`	Unique reporter UUID — used for domain verification
`reporter_token`	`string`	Upstream reporter token (managed internally — you authenticate with your WAYSCloud API key)
`oid`	`string`	Norwegian NKOM Object Identifier for this reporter
`trust_score`	`number`	Initial trust score (0.4 automated, 0.6 hybrid, 0.8 manual)
`status`	`string`	Reporter status (active)
`usage`	`object`	Instructions for submitting reports

Example:

bash

curl -X POST https://api.wayscloud.services/v1/ip/reporters/register \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ACME Security Lab",
  "source_type": "hybrid",
  "contact": "security@acme.com",
  "intent": "fail2ban + manual incident review",
  "domain": "acme.com"
}'

Response:

json

{
  "reporter_id": "550e8400-e29b-41d4-a716-446655440000",
  "reporter_token": "wayscloud_abc123...",
  "oid": "2.16.578.1.62.reporter.550e8400",
  "trust_score": 0.4,
  "status": "active",
  "usage": {
    "report_endpoint": "POST /v1/ip/report",
    "auth": "Use your WAYSCloud API key (same X-API-Key header)"
  }
}

POST /v1/ip/reporters/verify

Verify reporter domain ownership

Verify that you own the domain associated with your reporter registration. This increases your trust score to 1.0 (maximum), meaning your reports carry the highest weight.

Steps:

Register with a domain via POST /v1/ip/reporters/register
Add a DNS TXT record: wayscloud-verify=<reporter_id> to your domain (or _wayscloud.yourdomain.com)
Call this endpoint to trigger verification

DNS propagation may take 5–15 minutes after adding the TXT record.

Request Body:

Field	Type	Description
`reporter_id`	`string`	Reporter UUID to verify (from registration response)
`domain`	`string`	Domain to verify (alternative to reporter_id — looks up the reporter by domain)

Example:

json

{
  "reporter_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "acme.com"
}

Response:

Field	Type	Description
`reporter_id`	`string`	Verified reporter UUID
`domain`	`string`	Verified domain
`trust_score`	`number`	Updated trust score (1.0 after verification)
`message`	`string`	Verification status message

Example:

bash

curl -X POST https://api.wayscloud.services/v1/ip/reporters/verify \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "reporter_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "acme.com"
}'

Response:

json

{
  "reporter_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "acme.com",
  "trust_score": 1.0,
  "message": "Domain ownership verified successfully"
}

POST /v1/ip/delist

Request IP delisting

Request removal or review of an IP address from WAYSCloud threat lists.

Dual verification required:

The request should ideally originate from the IP being delisted (IP verification)
You must provide a hostname (e.g. mail.example.com) that resolves to the IP
After submitting, add a DNS TXT record: wayscloud-delist=<request_id> on the hostname

Common use cases:

Server was compromised but is now secured
Inherited a "dirty" IP from previous owner
False positive / misclassification
Shared hosting or VPN service

Timeline: Requests are reviewed within 24–48 hours after DNS verification.

Request Body:

Field	Type	Description
`ip_address`	`string`	Required. IPv4 or IPv6 address to request delisting for
`hostname`	`string`	Required. Hostname that resolves to this IP (e.g. mail.example.com). Used for DNS-based ownership verification
`reason`	`string`	Required. Detailed reason for the delist request (minimum 20 characters). Explain what happened and what remediation was done
`contact_email`	`string`	Required. Email address for follow-up communication about the delist request

Example:

json

{
  "ip_address": "157.180.31.156",
  "hostname": "mail.example.com",
  "reason": "Server was compromised via outdated WordPress plugin. Now fully patched, firewall updated, and malware removed.",
  "contact_email": "admin@example.com"
}

Response:

Field	Type	Description
`request_id`	`string`	Unique request UUID — use this in your DNS TXT record for verification
`ip_address`	`string`	The IP address in the delist request
`hostname`	`string`	The hostname provided for DNS verification
`verification_status`	`string`	Current verification state (ip_verified, dns_pending, fully_verified)
`dns_verification`	`object`	DNS TXT record instructions for completing verification
`message`	`string`	Next steps for completing the delist process

Example:

bash

curl -X POST https://api.wayscloud.services/v1/ip/delist \
  -H "X-API-Key: wayscloud_ipintel_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "ip_address": "157.180.31.156",
  "hostname": "mail.example.com",
  "reason": "Server was compromised via outdated WordPress plugin. Now fully patched, firewall updated, and malware removed.",
  "contact_email": "admin@example.com"
}'

Response:

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "ip_address": "157.180.31.156",
  "hostname": "mail.example.com",
  "verification_status": "ip_verified",
  "dns_verification": {
    "txt_record": "wayscloud-delist=550e8400-e29b-41d4-a716-446655440000",
    "instructions": [
      "Add TXT record to mail.example.com",
      "Test with: dig TXT mail.example.com +short"
    ]
  },
  "message": "Delist request submitted. Add DNS TXT record to complete verification."
}

IP Intelligence API ​

Endpoints ​

GET /v1/ip/ ​

GET /v1/ip/{ip}/geo ​

GET /v1/ip/{ip}/threat ​

GET /v1/ip/threats/live ​

GET /v1/ip/countries/ ​

GET /v1/ip/asn/ ​

POST /v1/ip/report ​

POST /v1/ip/reporters/register ​

POST /v1/ip/reporters/verify ​

POST /v1/ip/delist ​

IP Intelligence API

Endpoints

GET /v1/ip/

GET /v1/ip/{ip}/geo

GET /v1/ip/{ip}/threat

GET /v1/ip/threats/live

GET /v1/ip/countries/

GET /v1/ip/asn/

POST /v1/ip/report

POST /v1/ip/reporters/register

POST /v1/ip/reporters/verify

POST /v1/ip/delist