Skip to main contentSkip to footer

API Reference

Référence complète de tous les Endpoints de la REST API v2 de ReportedIP, avec des exemples de code en cURL, PHP, Python et JavaScript.

Quotas quotidiens par niveau : Gratuit 1,000 checks · 50 reports · Contributor 5,000 / 200 · Professional 25,000 / 1,000 · Business 100,000 / 5,000 par licence · Enterprise unlimited. Les quotas « Business » évoluent en fonction du nombre de licences (x2 à x20), par exemple x5 = 500,000 / 25,000. Consultez la page Tarifs pour une comparaison complète des niveaux.
Base URL https://reportedip.com/wp-json/reportedip/v2/
Authentification : les endpoints authentifiés nécessitent une API Key envoyée via l’ X-Key en-tête. Les Endpoints publics ne nécessitent pas d’authentification mais sont soumis à des Rate Limits. Les clés, les niveaux de service, les Rate Limits et les codes d’erreur sont expliqués en détail sur la page Authentification et Rate Limits.
Comment les quotas sont comptabilisés (depuis la v2.5.1) : chaque Endpoint ne compte au maximum qu’une fois par jour, jamais les deux.
  • Vérification du quota : GET /check (+1) et POST /bulk-check (+N, un par adresse IP valide).
  • Rapport de quota : POST /report (+1) et POST /bulk-report (+N, un par rapport soumis).
  • Aucun des deux quotas : GET /blacklist, /blacklist-categories, /blacklist-stats, /reports/{ip}, /trends, /statistics, /verify-key — il s’agit de fonctionnalités soumises à des paliers d’accès, et non d’appels facturés à l’unité.
  • Limite d’adresses IP publiques : 100 requêtes par jour par adresse IP source, réparties entre tous les appels non authentifiés (/check-public, /stats-public, /search-public, /categories). Envoyez un X-Key en-tête pour basculer vers le chemin de quota par API Key à la place. /attack-map-data n’est pas comptabilisé.

Public Endpoints

Ces endpoints sont accessibles sans authentification. Limitation de débit à 100 requêtes par jour et par adresse IP.

GET /check-public — Public IP Check

Public

Check the reputation of an IP address without authentication. Returns abuse confidence score, total reports, threat categories, and last report date. Counts +1 against the per-IP public-API daily limit (shared with the other unauthenticated endpoints).

Public limit: 100 requests/day per source IP, shared across all unauthenticated endpoints. Send an X-Key header to switch to the API-key quota path.

Parameters

Name Type Required Default Description
ip string Yes IPv4 or IPv6 address to check
verbose boolean No false Include detailed confidence breakdown in response

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/check-public?ip=1.2.3.4"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/check-public?ip=1.2.3.4'
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/check-public',
    params={'ip': '1.2.3.4'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/check-public?ip=1.2.3.4'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "ip": "1.2.3.4",
    "abuseConfidencePercentage": 87,
    "totalReports": 42,
    "lastReportedAt": "2026-03-09T14:22:31Z",
    "categories": [18, 21, 22],
    "countryCode": "CN",
    "isp": "China Telecom"
  }
}

GET /stats-public — Detailed Public Statistics

Public

Retrieve extended public statistics with category breakdowns, top threat types, and historical data. Counts +1 against the per-IP public-API daily limit.

Public limit: 100 requests/day per source IP, shared across all unauthenticated endpoints.

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/stats-public"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/stats-public'
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/stats-public'
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/stats-public'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "totalIPs": 158432,
    "totalReports": 892741,
    "last24h": {
      "newIPs": 342,
      "newReports": 1847
    },
    "last7d": {
      "newIPs": 2156,
      "newReports": 12493
    },
    "categoryBreakdown": [
      {"id": 18, "name": "Brute-Force", "count": 45231},
      {"id": 21, "name": "Web App Attack", "count": 32198},
      {"id": 22, "name": "SSH", "count": 28764},
      {"id": 15, "name": "Port Scan", "count": 18432}
    ],
    "topCountries": [
      {"code": "CN", "count": 42156},
      {"code": "US", "count": 18743},
      {"code": "RU", "count": 15892}
    ]
  }
}

GET /search-public — Public IP Search

Public

Search the public reputation database by partial IP, country code, or ASN. Useful for the public-facing search bar on reportedip.com. Counts +1 against the per-IP public-API daily limit.

Public limit: 100 requests/day per source IP, shared across all unauthenticated endpoints. Results are capped at 50 entries per call.

Parameters

Name Type Required Default Description
q string Yes Search query: full or partial IP, country code (e.g. "CN"), or ASN.
limit int No 20 Number of results (max 50).

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/search-public?q=1.2.3"

Response

200 OK
json
{
  "meta": {"success": true, "code": 200},
  "data": {
    "query": "1.2.3",
    "results": [
      {"ip": "1.2.3.4", "abuseConfidencePercentage": 87, "totalReports": 42, "countryCode": "CN"},
      {"ip": "1.2.3.5", "abuseConfidencePercentage": 65, "totalReports": 12, "countryCode": "CN"}
    ]
  }
}

GET /categories — Threat Categories

Public

Retrieve the list of all 30 predefined threat categories used for classifying IP reports. Each category includes its ID, name, description, and severity level. Counts +1 against the per-IP public-API daily limit when called without an API key; with an X-Key header it does not count against any daily quota.

Public limit: 100 requests/day per source IP, shared across all unauthenticated endpoints. Send an X-Key header to bypass the public limit (no per-call quota when authenticated).

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/categories"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/categories'
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/categories'
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/categories'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": [
    {
      "id": 1,
      "name": "DNS Compromise",
      "description": "Compromised DNS server or DNS hijacking",
      "severity_level": 8
    },
    {
      "id": 18,
      "name": "Brute-Force",
      "description": "Login brute-force attempts",
      "severity_level": 7
    },
    {
      "id": 21,
      "name": "Web App Attack",
      "description": "Web application attacks (SQLi, XSS, etc.)",
      "severity_level": 9
    }
  ]
}

GET /attack-map-data — Live Attack Map Dataset

Public

Aggregated dataset that powers the live attack map on reportedip.com. Returns per-country report counts (top 50), the rolling 24-hour set of cross-country attack connections (top 30, same-country pairs excluded) and a today-logs counter. Cached server-side for 30 minutes — repeat calls within that window all hit the cache. Does not count against any daily quota.

Unmetered — does not count against the per-IP public limit. Response is cached server-side for 30 minutes, so a polling client should respect that interval.

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/attack-map-data"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/attack-map-data'
);
$data = json_decode( wp_remote_retrieve_body( $response ), true );
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/attack-map-data'
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/attack-map-data'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "country_data": {
      "CN": { "count": 42156, "avgThreat": 7.8 },
      "US": { "count": 18743, "avgThreat": 5.4 },
      "RU": { "count": 15892, "avgThreat": 7.1 }
    },
    "country_info": { },
    "total_reports": 76791,
    "max_reports": 42156,
    "recent_attacks": [
      {
        "id": 1,
        "source_country": "CN",
        "target_country": "DE",
        "confidence_score": 88,
        "attack_count": 214
      }
    ],
    "today_logs": 1847
  }
}

Endpoints authentifiés

Ces endpoints nécessitent une API Key valide envoyée via l’ X-Key en-tête. Récupérez votre API Key depuis le Dashboard.

GET /check — Full IP Check

API Key

Perform a full IP reputation check with detailed data. Returns comprehensive threat data including confidence breakdown, report history, and ISP information. Charges +1 against your daily check quota.

Parameters

Name Type Required Default Description
ip string Yes IPv4 or IPv6 address to check
verbose boolean No false Include detailed confidence score breakdown
include_reports boolean No false Include individual report details in response

Examples

curl
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/check?ip=1.2.3.4&verbose=true"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/check?ip=1.2.3.4&verbose=true',
    array(
        'headers' => array(
            'X-Key' => 'YOUR_API_KEY',
        ),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/check',
    params={'ip': '1.2.3.4', 'verbose': 'true'},
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/check?ip=1.2.3.4&verbose=true',
    {
        headers: { 'X-Key': 'YOUR_API_KEY' }
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "ip": "1.2.3.4",
    "abuseConfidencePercentage": 87,
    "totalReports": 42,
    "lastReportedAt": "2026-03-09T14:22:31Z",
    "categories": [18, 21, 22],
    "countryCode": "CN",
    "isp": "China Telecom",
    "isWhitelisted": false,
    "confidenceBreakdown": {
      "reportScore": 24.0,
      "diversityScore": 12.0,
      "recencyWeight": 13.5,
      "severityWeight": 12.3,
      "honeypotBonus": 25.0,
      "maxConfidence": 100,
      "constraintReasons": []
    },
    "debugInfo": {
      "reportCount": 42,
      "uniqueReporters": 8,
      "honeypotReportsCount": 5,
      "effectiveReportCount": 47,
      "timeDampeningFactor": 0.92
    }
  }
}

POST /report — Report IP Address

API Key

Report a malicious IP address to the community. The report will be aggregated with existing data to update the IP's abuse confidence score. Reports from the same reporter for the same IP within 5 minutes are automatically aggregated. Charges +1 against your daily report quota only — never against the check quota.

Parameters

Name Type Required Default Description
ip string Yes IPv4 or IPv6 address to report
categories array Yes Array of threat category IDs (e.g. [18, 21])
comment string No Optional comment describing the observed malicious activity

Examples

curl
curl -X POST \
     -H "X-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ip": "1.2.3.4", "categories": [18, 21], "comment": "SSH brute force"}' \
     "https://reportedip.com/wp-json/reportedip/v2/report"
php
$response = wp_remote_post(
    'https://reportedip.com/wp-json/reportedip/v2/report',
    array(
        'headers' => array(
            'X-Key'        => 'YOUR_API_KEY',
            'Content-Type' => 'application/json',
        ),
        'body' => wp_json_encode(array(
            'ip'         => '1.2.3.4',
            'categories' => array(18, 21),
            'comment'    => 'SSH brute force',
        )),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.post(
    'https://reportedip.com/wp-json/reportedip/v2/report',
    json={
        'ip': '1.2.3.4',
        'categories': [18, 21],
        'comment': 'SSH brute force'
    },
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/report',
    {
        method: 'POST',
        headers: {
            'X-Key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            ip: '1.2.3.4',
            categories: [18, 21],
            comment: 'SSH brute force'
        })
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "Report submitted successfully"
  },
  "data": {
    "reportId": 58234,
    "ip": "1.2.3.4",
    "categories": [18, 21],
    "abuseConfidencePercentage": 89
  }
}

GET /verify-key — Verify API Key

API Key

Verify your API key and retrieve account details including user role, permissions, rate limits, and current usage statistics. Does not count against any daily quota.

Examples

curl
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/verify-key"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/verify-key',
    array(
        'headers' => array(
            'X-Key' => 'YOUR_API_KEY',
        ),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/verify-key',
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/verify-key',
    {
        headers: { 'X-Key': 'YOUR_API_KEY' }
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "valid": true,
    "role": "reportedip_professional",
    "permissions": {
      "check": true,
      "report": true,
      "bulk_check": true,
      "bulk_report": false,
      "reports_detail": true,
      "trends": true
    },
    "rateLimits": {
      "checksPerDay": 25000,
      "reportsPerDay": 1000
    },
    "usage": {
      "checksToday": 1247,
      "reportsToday": 38
    }
  }
}

GET /statistics — Service Statistics

Public

Public, service-wide statistics: total tracked IPs, total reports, reports submitted today and active API keys. No API key required — rate-limited per IP like the other public endpoints. Does not count against any daily quota. Your personal usage and quota figures live in the <a href="https://reportedip.com/dashboard/">Dashboard</a>.

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/statistics"

Response

200 OK
json
{
  "meta": {"success": true, "code": 200},
  "data": {
    "total_ips": 181402,
    "total_reports": 2643918,
    "reports_today": 10457,
    "active_api_keys": 312
  }
}

Endpoints de la Blacklist

Accédez à la Blacklist d’adresses IP alimentée par la communauté, dont la notation est calculée automatiquement à partir de Reports en temps réel. Disponible aux formats JSON, texte brut et CSV pour l’intégration à un pare-feu.

GET /blacklist — Get Blacklist

API Key

Retrieve the IP blacklist in various formats. Supports filtering by confidence level and threat category — combine both to build service-specific block lists (SSH, mail, web, FTP). Lists are regenerated server-side every 15 minutes; the endpoint returns an ETag and honors If-None-Match, so unchanged lists answer with 304 Not Modified. Does not count against any daily quota — tier-gated feature (Contributor and up).

Parameters

Name Type Required Default Description
format string No json Response format: json, txt, or csv
source string No dynamic Blacklist source: dynamic (default) — the community-driven, automatically scored blacklist. Other values are reserved for internal use
confidence integer No 75 Minimum abuse confidence percentage (0-100). Alias: confidenceMinimum. Recommended for automated blocking: 90
category string No One or more threat category IDs, comma-separated (e.g. 22,18 for an SSH block list). Full catalogue via GET /categories
limit integer No 10000 Maximum number of entries to return. Keep the default — smaller values truncate the list

Examples

curl
# JSON format
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90"

# Plain text (one IP per line, for firewall rules)
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90&format=txt&limit=10000"

# Service-specific list: SSH attackers only (categories 22 + 18)
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90&format=txt&limit=10000&category=22,18"

# Conditional request: returns 304 Not Modified if the list is unchanged
curl -H "X-Key: YOUR_API_KEY" \
     -H 'If-None-Match: W/"2438413-90-2f6c8ad881b6"' \
     "https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90&format=txt&limit=10000"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90',
    array(
        'headers' => array(
            'X-Key' => 'YOUR_API_KEY',
        ),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist',
    params={
        'confidence': 90,
        'format': 'txt',
        'limit': 10000,
        'category': '22,18'
    },
    headers={'X-Key': 'YOUR_API_KEY'}
)
ips = response.text.splitlines()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist?confidence=90',
    {
        headers: { 'X-Key': 'YOUR_API_KEY' }
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "generatedAt": "2026-07-21T17:43:13+00:00",
    "confidence": "90",
    "confidenceMinimum": "90",
    "count": 4821,
    "format": "reportapi_v2"
  },
  "data": [
    {
      "ip": "1.2.3.4",
      "ipAddress": "1.2.3.4",
      "abuseConfidencePercentage": 100,
      "lastReportedAt": "2026-07-21T14:22:31+00:00"
    },
    {
      "ip": "5.6.7.8",
      "ipAddress": "5.6.7.8",
      "abuseConfidencePercentage": 95,
      "lastReportedAt": "2026-07-21T13:45:12+00:00"
    }
  ]
}

GET /blacklist-categories — Blacklist Categories

Public

Retrieve all available blacklist categories used for classifying entries. Does not count against any daily quota.

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/blacklist-categories"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-categories'
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-categories'
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-categories'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": [
    {
      "id": 1,
      "name": "Botnet",
      "slug": "botnet",
      "description": "Known botnet command and control or participant"
    },
    {
      "id": 2,
      "name": "Brute-Force",
      "slug": "brute-force",
      "description": "Credential brute-force attacks"
    },
    {
      "id": 3,
      "name": "Spam",
      "slug": "spam",
      "description": "Spam sources"
    }
  ]
}

GET /blacklist-stats — Blacklist Statistics

Public

Retrieve statistics about the blacklist including total counts and distribution by confidence level and category. Does not count against any daily quota.

Examples

curl
curl "https://reportedip.com/wp-json/reportedip/v2/blacklist-stats"
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-stats'
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-stats'
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/blacklist-stats'
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "total": 12483,
    "community": 12483,
    "byConfidence": {
      "90-100": 4821,
      "75-89": 3247,
      "50-74": 2891,
      "25-49": 1524
    },
    "byCategory": [
      {"name": "Brute-Force", "count": 5432},
      {"name": "Web App Attack", "count": 3218},
      {"name": "SSH", "count": 2847},
      {"name": "Port Scan", "count": 986}
    ]
  }
}

Endpoints avancés

Points de terminaison avancés destinés aux utilisateurs expérimentés. Nécessitent des API Keys des niveaux « Professional » ou « Enterprise ».

GET /reports/{ip} — Reports for IP

Professional+

Retrieve all individual reports for a specific IP address. Returns paginated report details including reporter info, categories, and timestamps. Does not count against any daily quota — tier-gated feature (Professional and up).

Parameters

Name Type Required Default Description
ip string Yes IPv4 or IPv6 address (in URL path)
page integer No 1 Page number for pagination
per_page integer No 25 Reports per page

Examples

curl
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.com/wp-json/reportedip/v2/reports/1.2.3.4?page=1&per_page=25"
php
$ip = '1.2.3.4';
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/reports/' . $ip . '?page=1',
    array(
        'headers' => array(
            'X-Key' => 'YOUR_API_KEY',
        ),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

ip = '1.2.3.4'
response = requests.get(
    f'https://reportedip.com/wp-json/reportedip/v2/reports/{ip}',
    params={'page': 1, 'per_page': 25},
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const ip = '1.2.3.4';
const response = await fetch(
    `https://reportedip.com/wp-json/reportedip/v2/reports/${ip}?page=1&per_page=25`,
    {
        headers: { 'X-Key': 'YOUR_API_KEY' }
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "ip": "1.2.3.4",
    "reports": [
      {
        "id": 58234,
        "categories": [18, 21],
        "comment": "SSH brute force with 500+ attempts",
        "reportedAt": "2026-03-09T14:22:31Z",
        "reporterRole": "honeypot",
        "aggregationCount": 12
      },
      {
        "id": 58102,
        "categories": [22],
        "comment": "Port scanning on TCP 22, 80, 443, 8080",
        "reportedAt": "2026-03-09T10:15:00Z",
        "reporterRole": "contributor",
        "aggregationCount": 0
      }
    ],
    "total": 42,
    "page": 1,
    "per_page": 25,
    "total_pages": 2
  }
}

POST /bulk-check — Bulk IP Check

Professional+

Check the reputation of multiple IP addresses in a single request. Accepts up to 1,000 IPs per request. Charges +N against your daily check quota where N is the number of valid IPs in the request. If the call would exceed the remaining quota the server returns HTTP 429 and the counter is not incremented.

Parameters

Name Type Required Default Description
ips array Yes Array of IPv4/IPv6 addresses (max 1,000)

Examples

curl
curl -X POST \
     -H "X-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ips": ["1.2.3.4", "5.6.7.8", "9.10.11.12"]}' \
     "https://reportedip.com/wp-json/reportedip/v2/bulk-check"
php
$response = wp_remote_post(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-check',
    array(
        'headers' => array(
            'X-Key'        => 'YOUR_API_KEY',
            'Content-Type' => 'application/json',
        ),
        'body' => wp_json_encode(array(
            'ips' => array('1.2.3.4', '5.6.7.8', '9.10.11.12'),
        )),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

response = requests.post(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-check',
    json={
        'ips': ['1.2.3.4', '5.6.7.8', '9.10.11.12']
    },
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-check',
    {
        method: 'POST',
        headers: {
            'X-Key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            ips: ['1.2.3.4', '5.6.7.8', '9.10.11.12']
        })
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "OK"
  },
  "data": {
    "results": [
      {
        "ip": "1.2.3.4",
        "abuseConfidencePercentage": 87,
        "totalReports": 42,
        "lastReportedAt": "2026-03-09T14:22:31Z",
        "categories": [18, 21, 22]
      },
      {
        "ip": "5.6.7.8",
        "abuseConfidencePercentage": 0,
        "totalReports": 0,
        "lastReportedAt": null,
        "categories": []
      },
      {
        "ip": "9.10.11.12",
        "abuseConfidencePercentage": 45,
        "totalReports": 3,
        "lastReportedAt": "2026-03-07T09:30:00Z",
        "categories": [15]
      }
    ],
    "checked": 3
  }
}

POST /bulk-report — Bulk Report

Enterprise

Submit multiple IP reports in a single request using CSV-formatted data. Designed for automated systems and honeypots that need to report large volumes of malicious activity. Charges +N against your daily report quota where N is the number of submitted reports. Never counts against the check quota.

Parameters

Name Type Required Default Description
csv string Yes CSV data with columns: IP, Categories, Comment (one report per line)

Examples

curl
curl -X POST \
     -H "X-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"csv": "1.2.3.4,18|21,SSH brute force\n5.6.7.8,22,Port scanning\n9.10.11.12,15|18,Distributed attack"}' \
     "https://reportedip.com/wp-json/reportedip/v2/bulk-report"
php
$csv = "1.2.3.4,18|21,SSH brute force\n";
$csv .= "5.6.7.8,22,Port scanning\n";
$csv .= "9.10.11.12,15|18,Distributed attack";

$response = wp_remote_post(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-report',
    array(
        'headers' => array(
            'X-Key'        => 'YOUR_API_KEY',
            'Content-Type' => 'application/json',
        ),
        'body' => wp_json_encode(array(
            'csv' => $csv,
        )),
    )
);
$data = json_decode(wp_remote_retrieve_body($response), true);
python
import requests

csv_data = """1.2.3.4,18|21,SSH brute force
5.6.7.8,22,Port scanning
9.10.11.12,15|18,Distributed attack"""

response = requests.post(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-report',
    json={'csv': csv_data},
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const csvData = [
    '1.2.3.4,18|21,SSH brute force',
    '5.6.7.8,22,Port scanning',
    '9.10.11.12,15|18,Distributed attack'
].join('\n');

const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/bulk-report',
    {
        method: 'POST',
        headers: {
            'X-Key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ csv: csvData })
    }
);
const data = await response.json();

Response

200 OK
json
{
  "meta": {
    "success": true,
    "code": 200,
    "message": "Bulk report processed"
  },
  "data": {
    "success_count": 3,
    "error_count": 0,
    "errors": []
  }
}

Endpoints de relais 2FA

Distribution gérée de l'authentification à deux facteurs (2FA) pour le plugin WordPress ReportedIP Hive. Les abonnements PRO+ peuvent mettre en file d'attente les e-mails et SMS d'authentification via ce relais ; le service utilise d'abord le quota mensuel inclus, puis recourt au solde du forfait prépayé une fois ce plafond atteint.

Quota mensuel inclus : Free / Contributor not eligible · Professional 500 mails · 25 SMS · Business 2,500 mails · 75 SMS · Enterprise fair-use unlimited. Les abonnements PRO et Business peuvent être rechargés via des forfaits prépayés (hive_mail_bundle_1000/5000/25000, hive_sms_bundle_50/200/500).
Protection contre les remboursements — « bundle_balance » est signé : un remboursement Stripe (charge.refunded) sur un forfait précédemment utilisé réduit le solde et peut le faire passer en dessous de zéro. Tant que le solde est négatif et que le quota inclus est épuisé, les envois échouent avec le statut HTTP 402 cap_reached_buy_bundle jusqu’à ce qu’un nouveau forfait soit acheté.

GET /relay-quota — Relay Quota Status

PRO / Business / Enterprise

Returns the inclusive monthly quota plus the prepaid bundle balance for both Mail and SMS relay. Used by the Hive plugin dashboard to render usage bars and bundle hints.

Examples

curl
curl -H 'X-Key: YOUR_API_KEY' \
     https://reportedip.com/wp-json/reportedip/v2/relay-quota
php
$response = wp_remote_get(
    'https://reportedip.com/wp-json/reportedip/v2/relay-quota',
    array( 'headers' => array( 'X-Key' => 'YOUR_API_KEY' ) )
);
$data = json_decode( wp_remote_retrieve_body( $response ), true );
python
import requests

response = requests.get(
    'https://reportedip.com/wp-json/reportedip/v2/relay-quota',
    headers={'X-Key': 'YOUR_API_KEY'}
)
data = response.json()
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/relay-quota',
    { headers: { 'X-Key': 'YOUR_API_KEY' } }
);
const data = await response.json();

Response

200 OK
json
{
  "tier": "professional",
  "role": "reportedip_professional",
  "mail": {
    "sent": 18,
    "queued": 0,
    "queued_total": 18,
    "failed": 0,
    "limit": 500,
    "inclusive_limit": 500,
    "inclusive_used": 18,
    "inclusive_available": 482,
    "bundle_balance": 1000,
    "bundle_eligible": true,
    "period_start": "2026-05-01T00:00:00Z",
    "period_end":   "2026-05-31T23:59:59Z"
  },
  "sms": {
    "sent": 3,
    "queued": 0,
    "queued_total": 3,
    "failed": 0,
    "limit": 25,
    "inclusive_limit": 25,
    "inclusive_used": 3,
    "inclusive_available": 22,
    "bundle_balance": 50,
    "bundle_eligible": true,
    "period_start": "2026-05-01T00:00:00Z",
    "period_end":   "2026-05-31T23:59:59Z"
  },
  "mail_bundle_balance": 1000,
  "sms_bundle_balance":  50
}

POST /relay-mail — Send 2FA Mail

PRO / Business / Enterprise

Queues a transactional 2FA mail through the SPF/DKIM/DMARC-verified relay. Consumes one slot from the inclusive monthly mail quota; once exhausted, one credit from `mail_bundle_balance`. Returns HTTP 402 when both are empty.

Parameters

Name Type Required Default Description
recipient string Yes Recipient email address
subject string Yes Mail subject line
body_html string No '' HTML body of the mail
body_text string No '' Plain-text body / fallback
reply_to string No '' Reply-To address — plain email or RFC 5322 <code>Display Name <email@host></code>
headers array No [] Additional mail headers
site_url string No '' Origin site URL (used for per-site daily caps and audit logs)

Examples

curl
curl -X POST \
     -H 'X-Key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"recipient":"user@example.com","subject":"Your 2FA code","body_html":"<p>Code: 123456</p>","body_text":"Code: 123456"}' \
     https://reportedip.com/wp-json/reportedip/v2/relay-mail
php
$response = wp_remote_post(
    'https://reportedip.com/wp-json/reportedip/v2/relay-mail',
    array(
        'headers' => array( 'X-Key' => 'YOUR_API_KEY', 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'recipient' => 'user@example.com',
            'subject'   => 'Your 2FA code',
            'body_html' => '<p>Code: 123456</p>',
            'body_text' => 'Code: 123456',
        ) ),
    )
);
python
import requests

response = requests.post(
    'https://reportedip.com/wp-json/reportedip/v2/relay-mail',
    headers={'X-Key': 'YOUR_API_KEY'},
    json={
        'recipient': 'user@example.com',
        'subject': 'Your 2FA code',
        'body_html': '<p>Code: 123456</p>',
        'body_text': 'Code: 123456',
    },
)
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/relay-mail',
    {
        method: 'POST',
        headers: { 'X-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
        body: JSON.stringify({
            recipient: 'user@example.com',
            subject: 'Your 2FA code',
            body_html: '<p>Code: 123456</p>',
            body_text: 'Code: 123456',
        }),
    }
);

Response

200 OK
json
{
  "ok": true,
  "queue_id": 48217,
  "remaining_quota": {
    "sent": 18,
    "queued": 1,
    "queued_total": 19,
    "failed": 0,
    "limit": 500,
    "inclusive_limit": 500,
    "inclusive_used": 19,
    "inclusive_available": 481,
    "bundle_balance": 1000,
    "bundle_eligible": true,
    "period_start": "2026-05-01T00:00:00Z",
    "period_end":   "2026-05-31T23:59:59Z"
  }
}

POST /relay-sms — Send 2FA SMS

PRO / Business / Enterprise

Queues a 2FA SMS via the managed worldwide relay. The body is server-side rendered from a registered template (e.g. <code>2fa_login</code>) so the actual code never appears in client logs. HTTP 402 when both the inclusive quota and the prepaid bundle are exhausted; HTTP 422 with code <code>country_not_supported</code> when the destination country is unavailable for cost or operational reasons; HTTP 429 when the recipient or per-site daily anti-fraud cap is hit.

Parameters

Name Type Required Default Description
recipient_phone string Yes Recipient phone in E.164 format (e.g. +49170...)
template_code string No '' Server-side template id, e.g. <code>2fa_login</code>. When set, the message is rendered server-side and <code>message</code> is ignored
template_vars object No {} Template variables: <code>{ code, expiry_min, lang? }</code>
message string No '' Raw message text — used only when no <code>template_code</code> is given. One of <code>message</code> or <code>template_code</code> is required (HTTP 422 otherwise)
site_url string No '' Origin site URL (used for per-site daily caps and audit logs)

Examples

curl
curl -X POST \
     -H 'X-Key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"recipient_phone":"+491701234567","template_code":"2fa_login","template_vars":{"code":"123456","expiry_min":5,"lang":"de"}}' \
     https://reportedip.com/wp-json/reportedip/v2/relay-sms
php
$response = wp_remote_post(
    'https://reportedip.com/wp-json/reportedip/v2/relay-sms',
    array(
        'headers' => array( 'X-Key' => 'YOUR_API_KEY', 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'recipient_phone' => '+491701234567',
            'template_code'   => '2fa_login',
            'template_vars'   => array( 'code' => '123456', 'expiry_min' => 5, 'lang' => 'de' ),
        ) ),
    )
);
python
import requests

response = requests.post(
    'https://reportedip.com/wp-json/reportedip/v2/relay-sms',
    headers={'X-Key': 'YOUR_API_KEY'},
    json={
        'recipient_phone': '+491701234567',
        'template_code': '2fa_login',
        'template_vars': {'code': '123456', 'expiry_min': 5, 'lang': 'de'},
    },
)
javascript
const response = await fetch(
    'https://reportedip.com/wp-json/reportedip/v2/relay-sms',
    {
        method: 'POST',
        headers: { 'X-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
        body: JSON.stringify({
            recipient_phone: '+491701234567',
            template_code: '2fa_login',
            template_vars: { code: '123456', expiry_min: 5, lang: 'de' },
        }),
    }
);

Response

200 OK
json
{
  "ok": true,
  "queue_id": 901,
  "remaining_quota": {
    "sent": 3,
    "queued": 1,
    "queued_total": 4,
    "failed": 0,
    "limit": 25,
    "inclusive_limit": 25,
    "inclusive_used": 4,
    "inclusive_available": 21,
    "bundle_balance": 50,
    "bundle_eligible": true,
    "period_start": "2026-05-01T00:00:00Z",
    "period_end":   "2026-05-31T23:59:59Z"
  }
}

Réponses d’erreur pour les endpoints de relais

StatutCodeSignification
401missing_api_key / invalid_api_keyL' X-Key en-tête est manquant, mal formé ou fait référence à une clé désactivée.
403tier_forbiddenLe niveau d'accès de l'appelant (Free tier / Contributor) ne lui permet pas de bénéficier de la livraison par relais.
402cap_reached_buy_bundleLe plafond mensuel inclus a été atteint et le solde du forfait prépayé est nul ou négatif suite à un remboursement. Achetez un forfait dans le Dashboard pour reprendre l'envoi.
402monthly_cap_reachedLe plafond mensuel inclus a été atteint pour un niveau ne donnant pas droit à un forfait.
429recipient_backoff / site_daily_capLimitation anti-fraude. L’ retry-after en-tête indique le délai d'attente.

Endpoints obsolètes

Ces Endpoints sont obsolètes et seront supprimés dans une prochaine version. Veuillez migrer vers les alternatives recommandées.

GET /blacklist-detailed — Detailed Blacklist (Deprecated)

API Key
Deprecated. Use GET /blacklist instead.

Previously returned a detailed blacklist. Kept alive for backward compatibility with older Hive installations. Does not count against any daily quota (since v2.5.1 — was counted as a check before).

GET /blacklist-combined — Combined Blacklist (Deprecated)

API Key
Deprecated. Use GET /blacklist instead.

Previously returned a combined blacklist from all sources. Kept alive for backward compatibility with older Hive installations. Does not count against any daily quota (since v2.5.1).

GET /blacklist-export/git — Git Export (Deprecated)

API Key
Deprecated. Use GET /blacklist?format=txt instead.

Previously exported the blacklist in plain text format for Git repository integration. Kept alive for backward compatibility. Does not count against any daily quota (since v2.5.1).

Dernière mise à jour : · Géré par l'équipe ReportedIP

Security Focused
GDPR Compliant
Made in Germany
Retour aux Docs