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:
Authorization: Bearer ftk_<id>_<secret>, orX-API-Key: ftk_<id>_<secret>.
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
| Limit | Per key |
|---|---|
| Lookups per day (UTC) | 1,000 |
| Burst | 5 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"
}
| Field | Meaning |
|---|---|
risk | 0–100 |
level | low, medium or high |
categories | network categories of the address |
reasons | what the address was seen as or doing (code), when it was last seen (lastSeen), and how much it adds to the risk (contribution) |
country | where the address is located: {"isoCode": "<ISO 3166-1 alpha-2>"}, or null when unknown; see data sources |
subdivisions | the region: at most one entry {"isoCode": "<ISO 3166-2 code after the hyphen>", "names": {"en": "<name>"}}, or [] when unknown |
city | the city: {"names": {"en": "<name>"}}, or null when unknown |
network | the AS number (asn), its organisation (org) and the country where the holder of the AS is registered (asCountry); each null when unknown |
data | the snapshot the answer comes from; stale is true when that data is older than 26 hours |
disputeUrl | where 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": "..."}}.
| Status | Code | When |
|---|---|---|
| 400 | invalid_ip | the path is not a single address |
| 400 | key_in_query | a key was sent in the query string |
| 401 | key_missing | no key header |
| 401 | key_invalid | the key is malformed, unknown or revoked, or its account is disabled |
| 429 | quota_exceeded | the daily quota is used up |
| 429 | rate_limited | the burst rate is exceeded |
| 503 | no_data | no 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 }
}
- One result per address, in the order sent, with
ipexactly as you sent it. - A batch is one request for the per-second burst. Each distinct address is one lookup of the daily quota; an address sent twice is answered twice and counted once, and an invalid one is not counted.
- When the quota runs out within a batch, the addresses after that point answer
"error": "quota", and the answer is still200. When it is used up before the request, the whole request gets429 quota_exceeded. - If the data cannot be read in time, every address gets unknown values and none is counted.
- A malformed batch is
400 invalid_batch(413over 8 KiB,415when not JSON). The batch is for servers: it sends no CORS headers.
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.