API Reference

IP Reputation

Check IP addresses against threat intelligence feeds for reputation scoring

Screen incoming traffic and user sign-ups against known threat intelligence feeds. IP reputation scoring identifies proxies, VPNs, botnets, and previously flagged addresses, helping you block suspicious activity before it reaches your application. Ideal for fraud prevention, account security, and risk-based access control.

multi-provider aggregationthreat categorizationcachingrisk scoring

Endpoint

POST /v1/ip/reputation
Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.
Open Swagger UI (interactive docs)

Request

{
  "ip": "203.0.113.42"
}

Request Fields

FieldTypeDescription
ip string IPv4 or IPv6 address to check

Response

{
  "ip": "203.0.113.42",
  "reputation": "SUSPICIOUS",
  "score": 72,
  "threats": [
    "proxy",
    "scanner"
  ],
  "sources": [
    "abuseipdb",
    "blocklist.de"
  ],
  "checkedAt": "2026-03-25T14:30:00Z"
}

Response Fields

FieldTypeDescription
ip string IPv4 or IPv6 address to check
reputation string IP reputation status (GOOD, SUSPICIOUS, BAD)
score number Risk/confidence score (0-100)
threats array List of detected threat categories
sources array Array of items
checkedAt string Timestamp of when the check was performed

Error Codes

StatusMeaning
200Request completed successfully
400Bad request — invalid or missing parameters
401Missing or invalid X-API-Key header
429Rate limit exceeded — check Retry-After header
500Internal server error

Common Error Scenarios

400 Invalid IP address

Request that triggers this:

{"ip": "999.999.999.999"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid IP", "status": 400, "detail": "'999.999.999.999' is not a valid IPv4 or IPv6 address"}

How to fix: Validate the IP format before sending. Use standard IPv4 (e.g., 203.0.113.42) or IPv6 (e.g., 2001:db8::1) format.

429 Rate limit exceeded

Request that triggers this:

(after 1000+ checks in 1 hour)

Error response:

{"type": "/problems/rate-limit", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded. Current limit: 1000 requests/hour"}

How to fix: Batch requests efficiently or upgrade your plan. Check the X-RateLimit-Remaining header to monitor usage.

Code Examples

curl -X POST /v1/ip/reputation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "ip": "203.0.113.42"
}' 
// Node.js (18+) or modern browser
const response = await fetch("/v1/ip/reputation", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ip": "203.0.113.42"
}),
});

const data = await response.json();
console.log(response.status, data);
import requests

response = requests.post(
    "/v1/ip/reputation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "ip": "203.0.113.42"
},
)

print(response.status_code)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "ip": "203.0.113.42"
}`)
	req, _ := http.NewRequest("POST", "/v1/ip/reputation", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}
{
  "name": "ip_reputation",
  "description": "Check IP addresses against threat intelligence feeds for reputation scoring",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/ip/reputation",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference