API Reference

All endpoints return a data + meta envelope. Cache state is exposed via X-Cache (hit / miss / stale), X-Cache-Expires and X-Query-Time-Ms headers.

Base URL 
https://one.gy
Authentication

The JSON API is a paid feature (Pro and Max plans). Authenticate every /api/v1 request with your API key, sent as an X-API-Key header or an Authorization: Bearer token. Create keys on your account page and see pricing for plans. Requests without a key from a paid plan return 401/403. 

curl https://one.gy/api/v1/ip/8.8.8.8 -H 'X-API-Key: YOUR_KEY'

The examples below omit the header for brevity — add it to every /api/v1 call. The open utility endpoints (/me, /stats, /data-quality, /geoip/status, /search/fields, /prompts) do not require a key.

Response envelope

Every successful response wraps the payload in this shape.

{
  "data": { ... },
  "meta": {
    "cached": true,
    "stale": false,
    "cache_expires_at": "2026-03-25T12:00:00Z",
    "source": "cache",
    "query_time_ms": 12
  }
}
Response headers
  • X-Cache — hit, miss, or stale
  • X-Query-Time-Ms — server-side processing time in milliseconds
  • X-Cache-Expires — RFC3339 expiry when a cache TTL is known
  • X-Request-Id — opaque correlation id (echoed back if supplied)
  • X-RateLimit-Remaining — tokens left in the global bucket
GET /health Service health

Checks the database and upstream RIPE Stat reachability.

Example
curl https://one.gy/health
Response fields
  • data.status
  • data.database
  • data.upstream
GET /api/v1/ip/:ip Lookup an IP

Returns the matched prefix, origin ASN list and geo for a single IP.

Example
curl https://one.gy/api/v1/ip/8.8.8.8
Response fields
  • data.ip
  • data.prefix
  • data.asns[]
  • data.country_code
  • data.geo
GET /api/v1/me Current request IP

Returns the caller's public IP as resolved from the socket or trusted reverse-proxy headers, plus lookup data when available.

Example
curl https://one.gy/api/v1/me
Response fields
  • data.ip
  • data.lookup.prefix
  • data.lookup.reputation
POST /api/v1/ip/bulk Bulk IP lookup

Lookup up to 100 IPs in one request; returns successes plus per-IP errors.

Example
curl -X POST https://one.gy/api/v1/ip/bulk \
  -H 'Content-Type: application/json' \
  -d '{"ips":["8.8.8.8","1.1.1.1"]}'
Response fields
  • data.results[]
  • data.errors[]
GET /api/v1/ip/:ip/whois WHOIS for an IP

Returns RIR authority records and IRR records for the IP.

Example
curl https://one.gy/api/v1/ip/8.8.8.8/whois
Response fields
  • data.resource
  • data.authorities[]
  • data.records[]
  • data.irr_records[]
GET /api/v1/ip/:ip/reputation IP reputation

Returns multi-source abuse intelligence, including Tor, known-proxy, blocklist/DNSBL, and threat-feed signals.

Example
curl https://one.gy/api/v1/ip/8.8.8.8/reputation
Response fields
  • data.score
  • data.verdict
  • data.flags.is_proxy
  • data.sources[]
GET /api/v1/asn/:asn ASN detail

Accepts a plain number or AS-prefixed value. Includes registry block and routing summary.

Example
curl https://one.gy/api/v1/asn/15169
Response fields
  • data.asn
  • data.holder
  • data.org_name
  • data.as_name
  • data.announced
  • data.block
  • data.routing
GET /api/v1/asn/:asn/prefixes Announced prefixes

Per-ASN list of announced prefixes with timelines (gzip recommended).

Example
curl https://one.gy/api/v1/asn/15169/prefixes
Response fields
  • data.asn
  • data.resource
  • data.prefixes[]
GET /api/v1/asn/:asn/peers ASN peers

Neighbour counts and observed peer relationships.

Example
curl https://one.gy/api/v1/asn/15169/peers
Response fields
  • data.asn
  • data.neighbour_counts
  • data.neighbours[]
GET /api/v1/prefix/:prefix/:cidr Lookup a prefix

Use <prefix>/<cidr> in the URL path. Returns origin ASN set and country code.

Example
curl https://one.gy/api/v1/prefix/8.8.8.0/24
Response fields
  • data.prefix
  • data.asns[]
  • data.country_code
GET /api/v1/stats Cache and service stats

Counters for hits, misses, stale serves, fallbacks, and cache sizes.

Example
curl https://one.gy/api/v1/stats
Response fields
  • data.cache_hits
  • data.cache_misses
  • data.hit_ratio
  • data.total_cache_entries
GET /api/v1/proxies/good Good proxy list

API-key gated JSON list of consensus-scored proxies. Supports protocol, country, ASN, anonymity, egress, reliability, success, latency, sort, and limit filters. The protocol, country, ASN, anonymity, and egress filters accept a comma-separated list (e.g. protocol=http,socks5) to match any of several values; a single value still works.

Example
curl 'https://one.gy/api/v1/proxies/good?protocol=http,socks5&country=US,DE' -H 'X-API-Key: <key>'
Response fields
  • data[].host
  • data[].port
  • data[].protocol
  • data[].reliability
  • data[].egress_label
POST /api/v1/proxies/stats Proxy stats ingest

First-party node ingest endpoint for absolute per-proxy counters. Requires a per-node credential from the unified node registry (enroll + admin approval).

Example
curl -X POST https://one.gy/api/v1/proxies/stats -H 'Authorization: Bearer <node-token>' -H 'Content-Type: application/json' -d '{"node":"node-1","install_id":"epoch-1","count":1,"proxies":[{"host":"8.8.8.8","port":8080,"protocol":"http","total_checks":5,"success_count":4,"failure_count":1,"consecutive_failures":0,"last_checked_at":1760000000}]}'
Response fields
  • data.accepted
  • data.rejected
  • data.node
GET /metrics Prometheus metrics

Prometheus text format. Suitable for direct scrape.

Example
curl https://one.gy/metrics
Response fields
  • asn_api_requests_total
  • asn_api_request_duration_seconds
  • asn_api_upstream_errors_total
  • asn_api_cache_events_total
Error model
  • 400 invalid input (malformed IP, ASN, prefix, or empty/oversized search)
  • 404 route not found or upstream confirms the resource does not exist
  • 429 rate limit exceeded; Retry-After: 1 always supplied
  • 502 upstream temporarily unavailable
  • 503 upstream circuit breaker open
  • 500 internal error (logged with request id)
Behavior notes
  • IP lookups fall back from RIPE Stat to Team Cymru on failure.
  • ASN lookups enrich from PeeringDB and serve from cache when RIPE is degraded.
  • Stale cache entries are served while a background refresh fires (X-Cache: stale).
  • Concurrent identical requests are coalesced into one upstream call.
  • All responses honour Accept-Encoding: gzip, br.