OpenAPI 3.1.0 · IPBGP Public API v2.1.0

API reference

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

For AI agents

Copy one complete prompt into your coding agent. The machine files below are the same public contract this page renders, so an agent can read them instead of scraping HTML.

Download ipbgp-agent.md

Authentication

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

Operations listed as Anonymous take no API key; they run under their own abuse, captcha and quota controls.

header

Authorization: Bearer ipbgp_live_xxx

Create and manage API keys in your dashboard →

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

Quickstart

Every call below is keyed — send your API key as a Bearer token, or the API answers 401. The root self-check classifies only the public IP making the request, so use the single-IP endpoint for any other address.

curl

# 1. Self-check: classify the public IP making this request
curl https://www.ipbgp.org \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 2. Classify any other IPv4 or IPv6 address
curl https://www.ipbgp.org/v1/ip/8.8.8.8 \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 3. Classify the authenticated caller IP
curl https://www.ipbgp.org/v1/me \
  -H "Authorization: Bearer ipbgp_live_xxx"

# 4. Bulk lookup
curl -X POST https://www.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"]}'

Look up a single IP in your language of choice:

curl https://www.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"
  }
}

Status	Meaning
400	Malformed request (e.g. invalid IP)
401	Missing or invalid API key
402	Payment required
403	Key scope insufficient for this endpoint
404	Not found
413	Bulk request too large
429	Rate limit / quota exceeded. See Retry-After header.
500	Internal error
501	Not implemented
502	Bad gateway
503	Service unavailable
504	Upstream timed out

Endpoints

GET/

Classify the caller IP

Classifies the address the request arrives from. A deployment may also name a customer-website URL for interactive browsers. When it does, a browser navigation to this path on the customer API host answers 302 to that absolute https URL before API-key authentication and without classifying the caller, so an unauthenticated browser is sent to the website instead of being answered 401. A browser navigation is a request whose Accept lists text/html and does not list application/json, whose User-Agent is a browser or whose Sec-Fetch-Mode is navigate, and whose User-Agent is not a known command-line client. Every other caller (curl, Accept: application/json, API clients) and every deployment that names no URL get the operation exactly as if the redirect did not exist.