OpenAPI 3.1.0 · IPBGP Public API v2.1.0

API reference

Authoritative customer contract for API-key IP and ASN lookups plus anonymous product-assist and Intel preview routes. Operational listeners and the paid Intel/submission surface are intentionally not part of this facet.

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

API assistant

Ask a quick question about endpoints, auth, errors, or response fields.

Try asking which endpoint to use for a single IP lookup or bulk request.

Your messages are processed by a model to generate the answer. This chat is not stored by default. A transcript is sent to sales only if you explicitly consent.

Authentication

IP lookup operations require your customer API key as a Bearer token. Operations marked Anonymous use their documented abuse, captcha and quota controls instead. 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

Start with the root self-check. It evaluates the public IP making this request only; use /v1/ip/{ip} with a Bearer key when you need to query any other IP.

curl

# 1. Public/full self-check for the IP making this request
curl https://ipbgp.org

# 2. Look up any IP (full verdict, API key required)
curl https://ipbgp.org/v1/ip/8.8.8.8 \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 3. Score your own caller IP with an API key
curl https://ipbgp.org/v1/me \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 4. 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"]}'

Query any IP in your language of choice:

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

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	Closed customer error envelope
401	Closed customer error envelope
402	Closed customer error envelope
403	Closed customer error envelope
404	Closed customer error envelope
413	Closed customer error envelope
429	Closed customer error envelope
500	Closed customer error envelope
501	Closed customer error envelope
502	Closed customer error envelope
503	Closed customer error envelope
504	Closed customer error envelope

Endpoints

GET/

Classify the caller IP

Authentication: API key Bearer

Responses

200IpResultCustomer-safe IP result400ErrorClosed customer error envelope401ErrorClosed customer error envelope402ErrorClosed customer error envelope403ErrorClosed customer error envelope429ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

GET/v1/ip/{ip}

Classify one IP address

Authentication: API key Bearer

Parameters

in

Responses

200IpResultCustomer-safe IP result400ErrorClosed customer error envelope401ErrorClosed customer error envelope402ErrorClosed customer error envelope403ErrorClosed customer error envelope429ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

GET/v1/me

Classify the authenticated caller IP

Authentication: API key Bearer

Responses

200IpResultCustomer-safe IP result400ErrorClosed customer error envelope401ErrorClosed customer error envelope402ErrorClosed customer error envelope403ErrorClosed customer error envelope429ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

POST/v1/ip/bulk

Classify a bounded list of IP addresses

Authentication: API key Bearer

Request body: BulkRequest

Responses

200BulkResponseOrdered bulk result400ErrorClosed customer error envelope401ErrorClosed customer error envelope402ErrorClosed customer error envelope403ErrorClosed customer error envelope413ErrorClosed customer error envelope429ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

GET/v1/asn/{asn}

Resolve a customer-safe ASN profile

Authentication: API key Bearer

Parameters

asn in path · required

Responses

200AsnProfileCustomer-safe ASN profile400ErrorClosed customer error envelope401ErrorClosed customer error envelope402ErrorClosed customer error envelope403ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope500ErrorClosed customer error envelope501ErrorClosed customer error envelope502ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

POST/v1/chat

Anonymous product assistant

Authentication: Anonymous

Request body: ChatRequest

Responses

200ChatReplyAssistant response400ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope503ErrorClosed customer error envelope

POST/v1/leads

Submit an anonymous sales lead

Authentication: Anonymous

Request body: LeadInput

Responses

200OkAccepted400ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope500ErrorClosed customer error envelope

GET/v1/public/intel/hosts/{ip}

Anonymous host Intel preview

Authentication: Anonymous

Parameters

in

Responses

200PublicIntelHostResponseAnonymous host response; locked callers receive the narrow preview and previously unlocked callers receive the full customer-safe projection. This shared contract covers the internal handler's 500 failures and the edge-derived listener's 502/503/504 upstream failures.400ErrorClosed customer error envelope404ErrorClosed customer error envelope500ErrorClosed customer error envelope502ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

POST/v1/public/intel/hosts/{ip}/unlock

Consume an anonymous host-preview unlock

Authentication: Anonymous

Parameters

in

Request body: CaptchaInput

Responses

200PublicIntelHostUnlockedResponseFull customer-safe host projection after a successful unlock400ErrorClosed customer error envelope401ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope500ErrorClosed customer error envelope502ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

GET/v1/public/intel/pivot

Consume an anonymous pivot preview

Authentication: Anonymous

Parameters

seed in query · required
depth in query
nodes in query
fanout in query
X-Captcha-Token in header

Responses

200PublicIntelPivotResponseAnonymous pivot preview400ErrorClosed customer error envelope401ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope500ErrorClosed customer error envelope502ErrorClosed customer error envelope503ErrorClosed customer error envelope504ErrorClosed customer error envelope

GET/v1/plans

List customer-safe public plan facts

Authentication: Anonymous

Responses

200PlanCatalogVersioned customer-safe public plan catalog404ErrorClosed customer error envelope503ErrorClosed customer error envelope

GET/v1/attributions

Static third-party source attribution registry

License-compliance page for the sources whose terms (CC-BY and similar) require visible credit. The registry is static product data - source name, license, canonical url, what the product uses it for, and the exact credit line - and is identical for every caller. It is never a per-query or per-answer source record: it says nothing about which source produced any individual answer, and callers must not read it as such. This is the one customer response deliberately served outside the redaction-whitelist presentation path, because its whole purpose is to name third parties. The page is static, strongly ETagged and cacheable for an hour; send `If-None-Match` to get 304 instead of the body. Only GET and HEAD are answered - any other method answers 405 with an `Allow` header, and a deployment that ships none of the licensed data does not mount the page at all, so the route then answers the standard 404.

Authentication: Anonymous

Responses

200AttributionRegistryStatic third-party attribution registry. Two representations of the same registry are content-negotiated on `Accept`, each with its own strong ETag and `Vary: Accept`: JSON by default (including `*/*` and browser Accept strings), and the ready-to-embed plain-text credit block when `text/plain` outranks `application/json`.304Registry unchanged; the caller's If-None-Match matched the current strong ETag. Body is empty.404ErrorClosed customer error envelope

POST/v1/feedback

Report a disputed classification verdict

Anonymous, rate-limited intake for "this verdict is wrong about my address". The submission is queued for human review; 202 acknowledges the queue write only and promises no verdict change. The response never restates the current verdict, so the route cannot be used as an unmetered lookup oracle.

Authentication: Anonymous

Request body: VerdictFeedbackInput

Responses

202VerdictFeedbackReceiptFeedback queued for review400ErrorClosed customer error envelope404ErrorClosed customer error envelope429ErrorClosed customer error envelope500ErrorClosed customer error envelope504ErrorClosed customer error envelope

Schemas

Error

Field	Type	Description
error*	object

IpResult

Field	Type	Description
ip*	string
version*	string
classification*	Classification
trust*	Trust
network	Network
anonymization	Anonymization
geography	Geography
abuse	Abuse
contacts	Contacts
activity	Activity
history	History
hostname	string
registry*	Registry
risks*	string[]
meta*	Meta

Classification

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

Trust

Field	Type	Description
score*	integer
risk_score*	integer
recommendation*	allow \| review \| block
residential_probability*	number
confidence*	integer
reasons	Reason[]
risk_factors	RiskFactor[]

Reason

Field	Type	Description
code*	string
category*	network \| measurement \| reputation \| location \| history
impact*	positive \| negative \| neutral
detail*	string

RiskFactor

Field	Type	Description
code*	string
category*	anonymization \| reputation \| infrastructure \| structural
severity*	low \| medium \| high
detail*	string

Network

Field	Type	Description
asn*	integer
asn_name	string
as_type*	string
customer_cone_size*	integer
upstream_asns	integer[]
prefix_upstream_asns	integer[]
prefix_upstream_regions	RegionUpstream[]
prefix	string
prefix_size	integer
prefix_stability	string
rpki_valid*	boolean \| string
aspa_status*	valid \| invalid \| unknown
label_scores	object
irr	string
origin_consistency	string
alternate_origins	integer[]
usage_tags	string[]
recently_allocated*	boolean
is_anycast*	boolean
anycast	Anycast
leasing	Leasing
carrier	Carrier
ipv6_iid	string

RegionUpstream

Field	Type	Description
vantage*	string
continent	string
upstreams*	integer[]

Anycast

Field	Type	Description
is_anycast*	boolean
suspected	boolean
confidence*	integer
instance_count	integer
methods	latency \| path_divergence \| routing \| known[]

Leasing

Field	Type	Description
leased*	boolean
leased_from	string
holder_org	string
confidence	number

Carrier

Field	Type	Description
name	string
country_code	string
mcc	string
mnc	string

Anonymization

Field	Type	Description
is_proxy*	boolean
is_vpn*	boolean
is_tor*	boolean
is_relay*	boolean
is_residential_proxy*	boolean
provider*	string \| null

Geography

Field	Type	Description
country_code	string
country	string
region	string
city	string
postal_code	string
street	string
address_precision	address \| city \| region \| country \| approximate
timezone	string
latitude	number
longitude	number
confidence*	integer
confidence_radius_km	number
accuracy*	rooftop \| city \| region \| country \| unannounced \| anycast \| unknown
method	string
source	geofeed \| irr \| whois \| registry

Abuse

Field	Type	Description
is_abuser*	boolean
abuse_score*	integer
abuse_velocity*	none \| low \| medium \| high
threat_types*	string[]
benign_scanner*	boolean

Contacts

Field	Type	Description
abuse*	Contact
noc*	Contact
sales*	Contact

Contact

Field	Type	Description
email	string
phone	string
website	string

Activity

Field	Type	Description
open_proxy*	boolean
tor_exit*	boolean
scanned*	boolean
last_seen	string
open_ports	integer[]
tls_cert	string

History

Field	Type	Description
available*	boolean
first_seen	string
last_seen	string
observation_count*	integer
asn_stability*	number
geo_stability*	number
stability*	string
ever_hosting*	boolean

Registry

Field	Type	Description
status*	allocated \| unallocated \| reserved \| unknown
rir	string
reservation	string

Meta

Field	Type	Description
query_time*	string
data_epoch	string
freshness	fresh \| recent \| stale

BulkRequest

Field	Type	Description
ips*	string[]

BulkResponse

Field	Type	Description
results*	IpResult[]

AsnProfile

Field	Type	Description
asn*	integer
version*	string
asn_name	string
as_type*	string
residential_prior*	number
usage_tags*	string[]
confidence*	integer
topology	AsnTopology

AsnTopology

Field	Type	Description
customer_cone_size*	integer
originated_prefixes*	integer
upstreams	integer[]
sample_customers	integer[]
truncated	boolean

ChatRequest

Field	Type	Description
messages*	ChatMessage[]
session_id	string
locale	string
challenge_token	string	Token supplied only after a chat abuse rule requests a challenge.

ChatMessage

Field	Type	Description
role*	user \| assistant
content*	string

ChatReply

Field	Type	Description
reply*	string
sources	ChatSource[]
mode*	generated \| fallback \| unavailable
locale*	string
challenge	ChatChallenge
handoff	ChatHandoff

ChatSource

Field	Type	Description
title*	string
url*	string

ChatChallenge

Field	Type	Description
required*	boolean
provider*	turnstile	Challenge provider identity; never the identity of a model or content provider.
action*	string

ChatHandoff

Field	Type	Description
suggested*	boolean
reason*	string

LeadInput

Field	Type	Description
email*	string
name	string
message	string
company	string
use_case	string
transcript	ChatMessage[]	Supplying a transcript requires explicit consent=true at runtime.
consent	boolean	Must be true when transcript is present; enforced by the lead runtime.

PlanCatalog

Field	Type	Description
revision*	string
plans*	PlanFact[]

PlanFact

Field	Type	Description
tier*	free \| pro \| business \| enterprise
public_name*	Free \| Pro \| Business \| Enterprise
api_level*	Summary \| Standard \| Advanced
price_usd_monthly	integer \| null	Omitted or null for contact-only plans.
contact_only*	boolean
public*	boolean
capabilities*	string[]

Ok

Field	Type	Description
ok*	boolean

AttributionRegistry

Field	Type	Description
revision*	string	YYYY-MM month the registry was last reconciled against the internal licence ledger. It is a publication revision, never a query time.
notice*	string	Page-level statement that this is a single aggregated disclosure and not a per-query source record.
sources*	Attribution[]

Attribution

Field	Type	Description
name*	string	Third-party source name as its licence requires it to be credited.
license*	licence identifier	Closed licence identifier. A source whose licence is not on this list is not published here at all.
url*	string	Canonical https url for the source or its licence.
used_for*	string	Plain-language statement of what the product uses the source for.
attribution_required*	boolean	True when the licence obliges us to display a credit line for this source; false for CC0 and public-domain rows, which are listed for transparency only.
attribution_text	string	Exact credit line to display. Present exactly when attribution_required is true.
since*	string	YYYY-MM month this source entered the product.

VerdictFeedbackInput

Field	Type	Description
subject*	string	IP address the disputed verdict was about.
predicted*	residential \| business \| hosting \| mobile \| datacenter \| education \| government \| satellite \| unknown	Classification the caller received. Same closed set as the classification connection type.
corrected*	residential \| business \| hosting \| mobile \| datacenter \| education \| government \| satellite \| unknown	Classification the caller believes is right. Same closed set as the classification connection type.
note	string
contact	string	Optional reply address; supplying it is consent to be contacted about this report.
challenge_token	string	Optional captcha challenge token. Spending a valid one buys a single extra submission past the per-IP rate limit after a 429; it grants no other authority and is never required.

VerdictFeedbackReceipt

Field	Type	Description
ok*	boolean
id*	string	Opaque receipt id for this report; carries no verdict facts.

CaptchaInput

Field	Type	Description
captcha_token	string

PublicIntelPreview

Field	Type	Description
mode*	string
locked	boolean
captcha_required	boolean
login_required	boolean
unlocks_remaining	integer
pivot_remaining	integer
active_checks_remaining	integer
message	string

PublicIntelHostResponse

Field	Type	Description

PublicIntelHostLockedResponse

Field	Type	Description
available*	boolean
host	PublicHostPreview
preview*	LockedPublicIntelPreview

PublicIntelHostUnlockedResponse

Field	Type	Description
available*	boolean
host	PublicHostExposure
preview*	UnlockedPublicIntelPreview

PublicHostPreview

Field	Type	Description
ip*	string
open_ports	integer[]
score*	number
labels	string[]
observed_at	string

PublicHostExposure

Field	Type	Description
ip*	string
os_context	OSContext
software	Software[]
open_ports	integer[]
services	Service[]
web_properties	WebProperty[]
vulns	Vulnerability[]
threats	Threat[]
cert	CertificateHealth
network	Network
geography	Geography
trust_context	TrustContext
ai_summary	AISummary
score*	number
labels	string[]
observed_at	string

OSContext

Field	Type	Description
family*	Linux-like \| Windows-like \| BSD-like \| network-device-like \| embedded-device-like \| unknown
confidence*	number
middlebox_affected*	boolean

Software

Field	Type	Description
product*	string
version	string
port	integer

Service

Field	Type	Description
port*	integer
transport_proto	string
service_name	string
software	string[]
labels	string[]
observed_at	string

WebProperty

Field	Type	Description
fqdn*	string
served*	boolean
resolves_to*	boolean
fcrdns*	boolean
port	integer
title	string
labels	string[]

Vulnerability

Field	Type	Description
cve*	string
cpe	string
severity	string
cvss_version	string
cvss	number
epss	number
epss_percentile	number
kev*	boolean
kev_date_added	string
exploit_maturity	string
ssvc	string
port	integer
confirmation	string
confidence	integer
observed_at	string

Threat

Field	Type	Description
family	string
actor	string
tactic	string
threat_type	string
confidence	integer
observed_at	string

CertificateHealth

Field	Type	Description
browser_trusted*	boolean
ever_valid*	boolean
revoked*	boolean
zlint_clean*	boolean
ever_seen_in_scan	string
reuse_count	integer

TrustContext

Field	Type	Description
classification	string
residential_prob*	number
anonymization	string[]

AISummary

Field	Type	Description
text	string
role	string
generated_at	string

LockedPublicIntelPreview

Field	Type	Description
mode*	string
locked*	boolean
captcha_required	boolean
login_required	boolean
unlocks_remaining	integer
pivot_remaining	integer
active_checks_remaining	integer
message	string

UnlockedPublicIntelPreview

Field	Type	Description
mode*	string
captcha_required	boolean
login_required	boolean
unlocks_remaining	integer
pivot_remaining	integer
active_checks_remaining	integer
message	string

PublicIntelPivotResponse

Field	Type	Description
graph*	ExposureGraph
preview*	PublicIntelPreview

ExposureGraph

Field	Type	Description
nodes	PivotNode[]
edges	PivotEdge[]
truncated	boolean

PivotNode

Field	Type	Description
kind*	string
value*	string
rarity	number

PivotEdge

Field	Type	Description
from*	string
to*	string
relation*	string