FoxTrust pre-alpha

API v1

One request, one address, one verdict. The verdict comes from the newest published, signed snapshot, the same data you can download, so it can always be reproduced from that snapshot. The AS, region and city of the address come from FoxTrust's data when you ask; the snapshots do not carry them.

Look up an address

curl -H "Authorization: Bearer ftk_..." https://api.foxtrust.dev/v1/ip/203.0.113.7

GET https://api.foxtrust.dev/v1/ip/{ip} takes an IPv4 address (dotted quad, no leading zeros) or an IPv6 address (no zone id). An IPv4-mapped IPv6 address is answered as the IPv4 address.

Keys

Every request needs a key, sent in a header:

A key in the query string is refused, so keys do not end up in proxy and browser logs. Call the API from your server rather than from a public web page. During pre-alpha the operator issues keys; creating your own keys on this site comes later. A key is shown once, when it is created.

Free tier

LimitPer key
Lookups per day (UTC)1,000
Burst5 per second

Every answer to a valid key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds of the next 00:00 UTC). Over a limit, the answer is 429 with Retry-After.

Answer

{
  "ip": "203.0.113.7",
  "risk": 64,
  "level": "high",
  "categories": ["hosting"],
  "reasons": [
    { "code": "ssh_bruteforce", "lastSeen": "2026-10-06T21:14:00Z", "contribution": 52 },
    { "code": "hosting", "lastSeen": "2026-10-07T00:00:00Z", "contribution": 12 }
  ],
  "country": { "isoCode": "NL" },
  "subdivisions": [{ "isoCode": "NH", "names": { "en": "North Holland" } }],
  "city": { "names": { "en": "Amsterdam" } },
  "network": { "asn": 64500, "org": "Example Hosting", "asCountry": "NL" },
  "data": { "version": "f20261007", "delta": "d20261007T09", "builtAt": "2026-10-07T09:05:12Z", "stale": false },
  "disputeUrl": "https://foxtrust.dev/dispute"
}
FieldMeaning
risk0–100
levellow, medium or high
categoriesnetwork categories of the address
reasonswhat the address was seen as or doing (code), when it was last seen (lastSeen), and how much it adds to the risk (contribution)
countrywhere the address is located: {"isoCode": "<ISO 3166-1 alpha-2>"}, or null when unknown; see data sources
subdivisionsthe region: at most one entry {"isoCode": "<ISO 3166-2 code after the hyphen>", "names": {"en": "<name>"}}, or [] when unknown
citythe city: {"names": {"en": "<name>"}}, or null when unknown
networkthe AS number (asn), its organisation (org) and the country where the holder of the AS is registered (asCountry); each null when unknown
datathe snapshot the answer comes from; stale is true when that data is older than 26 hours
disputeUrlwhere the owner of a listed address can dispute it

country and network.asCountry can differ. A leased block or a VPN server can be located in one country and announced by an AS registered in another. Use country for where the address is, and asCountry only for the network's registration.

network, region and city are not in the published snapshots: the API reads them from FoxTrust's data when you ask, so they can be newer than data.version. Region and city are given only where their country is the one in country; they never change the risk. Location data: IP Geolocation by DB-IP, CC BY 4.0. Pages that show country, a region or a city must keep this notice.

An address that is not listed gets risk 0, level low and no reasons. That is an answer, not an error.

Errors

Errors have the body {"error": {"code": "...", "message": "..."}}.

StatusCodeWhen
400invalid_ipthe path is not a single address
400key_in_querya key was sent in the query string
401key_missingno key header
401key_invalidthe key is malformed, unknown or revoked, or its account is disabled
429quota_exceededthe daily quota is used up
429rate_limitedthe burst rate is exceeded
503no_datano snapshot is loaded yet; retry after Retry-After seconds

Only lookups that get a verdict count against the quota.

Look up many addresses

curl -X POST -H "Authorization: Bearer ftk_..." -H "Content-Type: application/json" \
     -d '{"ips": ["203.0.113.7", "2001:db8::1"]}' https://api.foxtrust.dev/v1/ip/batch

POST https://api.foxtrust.dev/v1/ip/batch takes {"ips": [...]} with 1 to 100 addresses, each as GET /v1/ip/{ip} takes it, in a body of at most 8 KiB. It answers only network, subdivisions and city of each address, with the same rules as above, and no risk, level, reasons, categories or country:

{
  "results": [
    { "ip": "203.0.113.7", "network": { "asn": 64500, "org": "Example Hosting", "asCountry": "NL" },
      "subdivisions": [{ "isoCode": "NH", "names": { "en": "North Holland" } }], "city": { "names": { "en": "Amsterdam" } } },
    { "ip": "2001:db8::1", "error": "invalid_ip" }
  ],
  "data": { "version": "f20261007", "delta": "d20261007T09", "builtAt": "2026-10-07T09:05:12Z", "stale": false }
}

Keys for FoxAuth servers

A FoxAuth server can get its own key without an account. It proves an Ed25519 key pair whose public half it has sent in its daily usage reports for at least 7 days, on at least 3 of them, and registers at POST https://api.foxtrust.dev/v1/foxauth/instance-keys with a signed request. Registering again gives a new key and revokes the old one. FoxAuth does this by itself; its operator can turn it off in the FoxAuth console. Instance keys have the free tier's limits and are counted like any key; FoxTrust does not store or log the addresses they look up.