HTTP Endpoints

GET /health

Returns the service status, version, and build commit. Subject to API key authentication when api_keys is configured.

Status codes

Code	Meaning
200 OK	Service is running.
401 Unauthorized	API key missing or invalid (only when api_keys is configured).

Response

Field	Type	Description
status	string	Always "ok" when the service is running.
version	string	Semantic version of the binary.
commit	string?	Short Git commit hash (7 chars) embedded at build time.

{
  "status": "ok",
  "version": "0.1.0",
  "commit": "abc1234"
}

---

GET /context/{ip}

Returns full context for an IP address: MMDB geo/network data plus activity across all buckets.

Path parameters

Parameter	Description
ip	IPv4 or IPv6 address

Status codes

Code	Meaning
200 OK	Lookup succeeded.
400 Bad Request	ip is not a valid IP address.
401 Unauthorized	API key missing or invalid (only when api_keys is configured).
404 Not Found	The IP was not found in any bucket.

Response

Field	Type	Description
ip	string	The queried IP address.
location.country_code	string?	ISO 3166-1 alpha-2 country code.
location.city	string?	City name.
location.timezone	string?	IANA timezone identifier.
network.asn	number?	Autonomous system number.
network.isp	string?	ISP name.
network.organization	string?	Organization name.
network.user_type	string?	Connection type (e.g. HOSTING, RESIDENTIAL).
enriched[].bucket	string	Bucket name.
enriched[].ttl	string?	Remaining TTL as [-][d.]hh:mm:ss[.fffffff]. null if the bucket has no expiry.
enriched[].providers[].provider	string	Provider identifier.
enriched[].providers[].count	number	Number of events recorded by this provider.
enriched[].providers[].last_seen	string	ISO 8601 UTC timestamp of the most recent event.

All location and network fields are null when MMDB data is unavailable for the IP.

{
  "ip": "1.3.3.7",
  "location": {
    "country_code": "US",
    "city": "Springfield",
    "timezone": "America/Chicago"
  },
  "network": {
    "asn": 31337,
    "isp": "Skynet Broadband",
    "organization": "Skynet Hosting Solutions",
    "user_type": "HOSTING"
  },
  "enriched": [
    {
      "bucket": "us_proxies",
      "ttl": "00:24:59",
      "providers": [
        {
          "provider": "totally-not-a-bot",
          "count": 7,
          "last_seen": "2026-02-19T14:30:00Z"
        }
      ]
    }
  ]
}

---

GET /context/{ip}/buckets/{bucket}

Returns activity for an IP address within a specific bucket.

Path parameters

Parameter	Description
ip	IPv4 or IPv6 address
bucket	Bucket name as defined in the config

Status codes

Code	Meaning
200 OK	Lookup succeeded.
400 Bad Request	ip is not a valid IP address.
401 Unauthorized	API key missing or invalid (only when api_keys is configured).
404 Not Found	The IP has no activity in this bucket.

Response

Field	Type	Description
ip	string	The queried IP address.
bucket	string	The queried bucket name.
ttl	string?	Remaining TTL as [-][d.]hh:mm:ss[.fffffff]. null if the bucket has no expiry.
enriched[].provider	string	Provider identifier.
enriched[].count	number	Number of events recorded by this provider.
enriched[].last_seen	string	ISO 8601 UTC timestamp of the most recent event.

{
  "ip": "1.3.3.7",
  "bucket": "us_proxies",
  "ttl": "00:24:59",
  "enriched": [
    {
      "provider": "totally-not-a-bot",
      "count": 7,
      "last_seen": "2026-02-19T14:30:00Z"
    }
  ]
}