OpenAPI 3.1.0 · ipbgp v1

API reference

IP trust / connection-type intelligence. For any IPv4/IPv6 address we return a classification, a trust score, and human-readable evidence — computed from our own data and our own detection nodes. Differentiators: trust.reasons (signed, neutral, explainable evidence), network (BGP/AS judgement) and activity (our own active measurement).

Rendered directly from the public OpenAPI contract — this page can't drift from the live API.

Authentication

Authenticate every request with a Bearer token — your customer API key. Keys are issued and managed in your dashboard.

header

Authorization: Bearer ipbgp_live_xxx

Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.

Quickstart

Look up a single IP in your language of choice:

curl https://ipbgp.org/v1/ip/8.8.8.8 \
  -H "Authorization: Bearer ipbgp_live_xxx"

More endpoints with curl:

curl

# 1. Look up a single IP (full verdict)
curl https://ipbgp.org/v1/ip/8.8.8.8 \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 2. Score your own caller IP
curl https://ipbgp.org/v1/me \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 3. Bulk lookup
curl -X POST https://ipbgp.org/v1/ip/bulk \
  -H "Authorization: Bearer ipbgp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8","1.1.1.1"]}'

Errors & rate limiting

Non-2xx responses use a uniform JSON body. On 429 a Retry-After header tells you when to retry.

error body

{
  "error": {
    "code": "rate_limited",
    "message": "Quota exceeded"
  }
}

400	Malformed request (e.g. invalid IP)
401	Missing or invalid API key
403	Key scope insufficient for this endpoint
413	Bulk request too large
429	Rate limit / quota exceeded — see Retry-After
500	Internal error
504	Upstream timed out

Endpoints

GET/v1/ip/{ip}

Full single-IP verdict (classification + trust + evidence + network…)

Parameters

ip in path · required — Target IPv4 / IPv6 address.

Responses

200IpResultVerdict (fields projected to your plan's field depth).400401403429

GET/v1/me

Verdict for the caller's own source IP

Responses

200IpResultVerdict for the caller IP.401429

POST/v1/ip/bulk

Batch IP verdicts (ordered to match the request)

Request body: BulkRequest

Responses

200BulkResponseVerdict array, in the same order as the requested ips.400401413429

GET/v1/asn/{asn}

ASN profile (operator identity + residential prior)

Parameters

asn in path · required — ASN, accepts "AS15169" or "15169".

Responses

200AsnProfileASN profile.400401

Schemas

IpResult

Field	Type	Description
ip*	string
version*	string
classification*	Classification
trust*	Trust
network	Network
anonymization	Anonymization
geography	Geography
abuse	Abuse
activity	Activity
contacts	Contacts
risks*	string[]	residential_proxy\|hosting_ip\|malware_c2\|serves_tls\|geoip_mismatch\|…
meta*	Meta

Classification

Field	Type	Description
connection_type*	residential \| business \| hosting \| mobile \| datacenter \| satellite \| unknown
is_residential*	boolean
is_hosting*	boolean
is_mobile*	boolean
is_datacenter*	boolean
type_confidence*	integer

Trust

Field	Type	Description
score*	integer	0–100 overall trust / real-user likelihood
residential_probability*	number
confidence*	integer
reasons	Reason[]	Explainable, neutral evidence. Standard tier and above.

Reason

Field	Type	Description
code*	string	Neutral reason code, e.g. residential_access_network
category*	prior \| network \| measurement \| reputation \| geo \| consistency \| temporal
impact*	positive \| negative \| neutral
detail*	string	Human-readable, English, no source names

Network

Field	Type	Description
asn*	integer
asn_name	string
as_type*	eyeball_isp \| hosting \| content \| transit \| enterprise \| unknown
customer_cone_size	integer
upstream_asns	integer[]	ASN-level upstream provider ASNs (inferred AS relationships)
prefix_upstream_asns	integer[]	this prefix's observed upstreams worldwide (anycast/multihomed → many)
prefix_upstream_regions	object[]	upstreams grouped by observing-vantage (BGP collector) location — anycast differs by region
prefix	string
prefix_size	integer
prefix_stability	stable \| churny \| recently_allocated
rpki_valid	boolean \| string	true\|false\|"unknown"
usage_tags	string[]	Neutral usage tags (e.g. residential, mobile).
recently_allocated	boolean
is_anycast	boolean
origin_rov_enforced	boolean	Origin AS deploys RPKI Route Origin Validation route filtering (route-hygiene trust signal).
leasing	Leasing
carrier	object	mobile carrier identity (cellular IPs only) — public ITU/operator facts, no source names
ipv6_iid	eui64 \| privacy_random \| static_low_byte \| embedded_ipv4 \| unknown	Structural class of the queried IPv6 address's interface identifier (low 64 bits) — pure address structure (residential vs infrastructure hint). Absent for IPv4.

Leasing

Field	Type	Description
leased*	boolean
leased_from	string \| null
holder_org	string \| null
confidence	integer

Anonymization

Field	Type	Description
is_proxy*	boolean
is_vpn*	boolean
is_tor*	boolean
is_relay*	boolean
is_residential_proxy*	boolean	Residential proxy exit node — core differentiator
provider	string \| null

Geography

Field	Type	Description
country_code	string
country	string
region	string
city	string
postal_code	string	Postal code from the geofeed/IRR declared address, surfaced whenever the declaration is country-accurate (independent registry/BGP country not contradicting). Read address_precision for how precise it is.
street	string	Street + house number from the geofeed/IRR declared address, surfaced whenever the declaration is country-accurate. Read address_precision for how precise it is.
address_precision	address \| city \| region \| country	Honest precision level of the surfaced street/postal — the value is given at its finest, the precision is stated plainly.
timezone	string	IANA timezone name (e.g. America/Los_Angeles), derived from country + coordinates.
latitude	number
longitude	number
confidence*	integer
confidence_radius_km	integer	Larger radius = less certain
method	string	registry_geoloc\|geofeed\|measurement\|measurement_corrected\|rdns\|database
registered_address	RegisteredAddress

RegisteredAddress

Field	Type	Description
street	string	Street + house number (highest precision text)
city	string
region	string
postal_code	string
country_code	string
country	string
precision*	address \| city \| region \| country	Granularity of this declared address text.
verified*	boolean	Whether cross-source checks corroborate the declared locality.
approximate*	boolean	true = an org/registry-level address (the organisation's HQ, shared across the whole block — NOT this IP's precise location). Returned only as a lowest-priority fallback when no more-precise source (per-prefix geofeed / IP database / IRR) located the IP. Treat as an imprecise result, never as the endpoint location.
source	geofeed \| whois \| irr \| rdap \| registry	Public registry channel (never a data-vendor name).
block_shared*	boolean	The address is derived per-prefix and shared across the whole block_prefix (not per-host).
block_prefix	string	The covering prefix that shares this declared address.

Abuse

Field	Type	Description
is_abuser*	boolean
abuse_score*	integer
abuse_velocity*	none \| low \| medium \| high
benign_scanner	boolean	known legitimate scanner/research probe (security/academic
categories	string[]	Our own categories when flagged, e.g. malware_c2, dynamic_pool. No source names.

Activity

Field	Type	Description
open_proxy*	boolean	Confirmed open HTTP CONNECT / SOCKS proxy
tor_exit*	boolean
scanned*	boolean
last_seen	string \| null	Date granularity (not a precise timestamp)

Contacts

Field	Type	Description
abuse	ContactChannel
noc	ContactChannel
sales	ContactChannel

ContactChannel

Field	Type	Description
email	string \| null
phone	string \| null
website	string \| null

Meta

Field	Type	Description
query_time*	string
data_epoch	string	Our snapshot epoch (a single date, not per-source timestamps)
freshness	fresh \| recent \| stale

AsnProfile

Field	Type	Description
asn*	integer
version*	string
asn_name	string
as_type*	eyeball_isp \| hosting \| content \| transit \| enterprise \| unknown
residential_prior*	number
tags*	string[]
confidence*	integer
meta*	object

BulkRequest

Field	Type	Description
ips*	string[]

BulkResponse

Field	Type	Description
results*	IpResult[]

ErrorBody

Field	Type	Description
error*	object