IP Intelligence API

Castle's IP intelligence provides reputation and infrastructure metadata for an IP address. For any given IP you get the autonomous system it belongs to, a coarse location, and any proxy or VPN tunnels Castle has recently observed on it.

This is the same intelligence that powers signals like proxy_ip, vpn_access, and residential_proxy_access in the risk API, exposed here as a standalone, queryable product. Instead of sending an event and reading the signals on the response, you query an entity directly and get back the raw data behind it. Use it to enrich your own systems, feed your own risk logic, or sync Castle's datasets into your infrastructure.

The API is exposed as a top-level resource under /v1, and offers three access patterns: a real-time lookup, a batch query, and downloadable datasets.

Authentication

The IP Intelligence API uses the same HTTP Basic authentication as the rest of the Castle API. Pass your API Secret as the basic-auth password and leave the username empty. You can find and manage your API Secret on the API keys page in the Castle dashboard.

Look up a single IP

Look up a single IP address and get its intelligence back immediately.

GET /v1/ips/{value}

Example request

curl -sSf -u ":$CASTLE_API_SECRET" \
  https://api.castle.io/v1/ips/1.0.105.13

Example response

{
    "address": "1.0.105.13",
    "type": "ipv4",
    "asn": 18144,
    "location": {
        "continent_code": "AS",
        "country_code": "JP"
    },
    "tunnels": [
        {
            "type": "proxy",
            "operator": "FloppyData residential",
            "tier": null,
            "last_seen_at": "2026-06-25T21:38:40.000Z",
            "proxy_type": "residential"
        },
        {
            "type": "proxy",
            "operator": "AnyIP residential",
            "tier": null,
            "last_seen_at": "2026-06-21T22:55:42.000Z",
            "proxy_type": "residential"
        }
    ]
}

Response fields

Each entry in tunnels describes one tunnel observation.

Batch query multiple IPs

Resolve many IP addresses in a single request. This is the most efficient way to enrich a set of IPs at once.

POST /v1/ips/query

The ips array accepts between 1 and 1,000 addresses per request. A request outside that range is rejected.

Example request

curl -sSf -X POST -u ":$CASTLE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ips": ["159.26.108.3", "1.0.105.13"] }' \
  https://api.castle.io/v1/ips/query

Example response

{
    "results": [
        {
            "address": "159.26.108.3",
            "type": "ipv4",
            "asn": 208172,
            "location": {
                "continent_code": "EU",
                "country_code": "SE"
            },
            "tunnels": []
        },
        {
            "address": "1.0.105.13",
            "type": "ipv4",
            "asn": 18144,
            "location": {
                "continent_code": "AS",
                "country_code": "JP"
            },
            "tunnels": [
                {
                    "type": "proxy",
                    "operator": "FloppyData residential",
                    "tier": null,
                    "last_seen_at": "2026-06-25T21:38:40.000Z",
                    "proxy_type": "residential"
                },
                {
                    "type": "proxy",
                    "operator": "AnyIP residential",
                    "tier": null,
                    "last_seen_at": "2026-06-21T22:55:42.000Z",
                    "proxy_type": "residential"
                }
            ]
        }
    ],
    "meta": {
        "total": 2,
        "valid": 2
    }
}

Each object in results uses the same schema as the real-time lookup. meta.total is the number of addresses submitted, and meta.valid the number of unique, parseable addresses that were resolved.

Download IP intelligence datasets

Datasets are precomputed snapshots of Castle's IP intelligence, delivered as gzipped files. They are a good fit for bulk enrichment, offline analysis, or syncing an allow or deny list into your own infrastructure.

GET /v1/ips/downloads/{dataset}/{window}.{format}.gz

• dataset. The dataset to download. proxies is currently the only available dataset.
• window. The lookback window for the snapshot, one of 1d, 7d, 30d, or 60d.
• format. The file format to download, either csv or jsonl.

Dataset columns

The proxies dataset is a tunnel feed, so each row is one tunnel observation rather than one IP address. An IP seen on several tunnels appears on several rows.

Example request

curl -LfOJ -u ":$CASTLE_API_SECRET" \
  "https://api.castle.io/v1/ips/downloads/proxies/1d.csv.gz"

The endpoint authenticates the request and then redirects to a time-limited download URL, so follow redirects with curl -L. Datasets are refreshed regularly. Each request returns the most recent snapshot.