---
title: IP Threat Intelligence API - VPN, Proxy & Tor Detection with Threat Scoring
version: 1.0.0
description: Retrieve real-time threat intelligence and security signals for a single IPv4 or IPv6 address. Returns an aggregate `threat_score` (0-100) plus detection flags and provider names for VPNs, proxies (including residential proxies), Tor exit nodes, relays, known attackers, bots, spam sources, and cloud-provider ranges. Use `fields`/`excludes` with dot notation (e.g. `security.threat_score`) to trim the response to only the modules you need. If `ip` is omitted, the API returns threat data for the public IP of the requesting client. Bogon and reserved IP addresses return a `423` error, and malformed IP input returns a `400` error, instead of partial data.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [IP Threat Intelligence API - VPN, Proxy & Tor Detection with Threat Scoring v1.0.0](#ip-threat-intelligence-api-vpn-proxy-tor-detection-with-threat-scoring-v100)
  - [Authentication](#authentication)
  - [IP Geolocation APIs](#ip-geolocation-apis)
    - [ipSecurityLookup](#ipsecuritylookup)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ErrorResponse](#errorresponse)
    - [IpSecurityResponse](#ipsecurityresponse)
    - [Security](#security)



# IP Threat Intelligence API - VPN, Proxy & Tor Detection with Threat Scoring v1.0.0

Retrieve real-time threat intelligence and security signals for a single IPv4 or IPv6 address. Returns an aggregate `threat_score` (0-100) plus detection flags and provider names for VPNs, proxies (including residential proxies), Tor exit nodes, relays, known attackers, bots, spam sources, and cloud-provider ranges. Use `fields`/`excludes` with dot notation (e.g. `security.threat_score`) to trim the response to only the modules you need. If `ip` is omitted, the API returns threat data for the public IP of the requesting client. Bogon and reserved IP addresses return a `423` error, and malformed IP input returns a `400` error, instead of partial data.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## IP Geolocation APIs

### ipSecurityLookup

`GET /ip/security`

*Retrieve real-time threat intelligence and security signals for an IPv4 or IPv6 address*

Get a threat score along with VPN, proxy, Tor, relay, bot, spam, known-attacker, and cloud-provider detection flags for an IP address.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response.|
|ip|query|string|false|IPv4 or IPv6 address to check for threat intelligence and security signals. If omitted, the public IP of the requesting client is used.|
|fields|query|string|false|Comma-separated list of fields to return. Supports dot notation (e.g. `security.threat_score`).|
|excludes|query|string|false|Comma-separated list of fields to remove from the response. Supports dot notation (e.g. `security.is_tor`). The `ip` field is always included and cannot be excluded.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful threat intelligence response

```json
{
  "ip": "8.8.8.8",
  "security": {
    "threat_score": 5,
    "is_tor": false,
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": "",
    "is_residential_proxy": false,
    "is_vpn": false,
    "vpn_provider_names": [],
    "vpn_confidence_score": 0,
    "vpn_last_seen": "",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": false,
    "is_known_attacker": false,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Google LLC"
  }
}
```

> Bad Request — Invalid or missing IP address

```json
{
  "message": "Provided IP address 'invalid' is not valid"
}
```

> Locked — Bogon or reserved IP address

```json
{
  "message": "'10.0.0.1' is a bogon IP address."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful threat intelligence response|[IpSecurityResponse](#ipsecurityresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid or missing IP address|[ErrorResponse](#errorresponse)|
|423|[Locked](https://tools.ietf.org/html/rfc2518#section-10.4)|Locked — Bogon or reserved IP address|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|423|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### ErrorResponse

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|

### IpSecurityResponse

Threat intelligence result for an IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ip|string|true|none|The IP address used for the lookup (IPv4 or IPv6).|
|security|[Security](#security)|false|none|Threat intelligence and security information for the IP.|

### Security

Threat intelligence and security information for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|threat_score|number|true|none|Aggregate risk score from 0 to 100.|
|is_tor|boolean|true|none|true if the IP matches a Tor exit node.|
|is_proxy|boolean|true|none|true if the IP is associated with a proxy service.|
|proxy_provider_names|[string]|false|none|Detected proxy provider names.|
|proxy_confidence_score|number|true|none|Proxy detection confidence from 0 to 100.|
|proxy_last_seen|string|false|none|Last observed proxy activity date in YYYY-MM-DD.|
|is_residential_proxy|boolean|true|none|true if the IP is linked to a residential proxy network.|
|is_vpn|boolean|true|none|true if the IP is associated with a VPN service.|
|vpn_provider_names|[string]|false|none|Detected VPN provider names.|
|vpn_confidence_score|number|true|none|VPN detection confidence from 0 to 100.|
|vpn_last_seen|string|false|none|Last observed VPN activity date in YYYY-MM-DD.|
|is_relay|boolean|true|none|true if the IP is associated with a relay network.|
|relay_provider_name|string|false|none|Relay provider name.|
|is_anonymous|boolean|true|none|true if any anonymity signal is present.|
|is_known_attacker|boolean|true|none|true if the IP is flagged for known attacker behavior.|
|is_bot|boolean|true|none|true if the IP is associated with bot activity.|
|is_spam|boolean|true|none|true if the IP is associated with spam activity.|
|is_cloud_provider|boolean|true|none|true if the IP belongs to a cloud provider range.|
|cloud_provider_name|string|false|none|Cloud provider name.|