ReachCheck API

Check whether a server IP is reachable from real home broadband connections, per country, across each network (ISP). Send one request with an IP and a country; you get back a reachable/blocked result for each ISP. Every request carries your key in the X-API-Key header.

Base URL
https://ip.builtforyou.dev/api/v1
Auth header
X-API-Key: rc_your_key_here

Keys are issued by the operator. Countries available now: GB, US, CA.

Start a check

At minimum send an ip and a country. The ISPs tested for that country are chosen for you, so you don't need to know ASNs.

POST /api/v1/checks
Content-Type: application/json
X-API-Key: rc_your_key_here

{
  "ip": "203.0.113.10",
  "port": 8080,
  "protocol": "http",          // tcp (port open?) | http | https
  "country": "GB"              // that's all you need; the ISPs are chosen for you
}

Optional fields to narrow or override what's tested:

{
  "providers": [5089, 2856],   // test exactly these ISPs (ASN numbers), instead of the default set
  "top_providers": 5,          // how many top ISPs to test when 'providers' is omitted (default 5)
  "webhook_url": "https://you.example.com/hook"  // we POST the finished result here
}

Returns 202 with an id and a URL to poll:

{ "id": "chk_1a2b3c4d", "status": "queued", "poll": "https://ip.builtforyou.dev/api/v1/checks/chk_1a2b3c4d" }

Get the result

GET /api/v1/checks/chk_1a2b3c4d
GET /api/v1/checks/chk_1a2b3c4d?wait=30   // hold the request up to 30s until it finishes
{
  "id": "chk_1a2b3c4d",
  "status": "done",
  "message": "reachable from 4 of 5 ISPs",
  "ip": "203.0.113.10", "port": 8080, "protocol": "http", "country": "GB",
  "summary": { "total": 5, "reachable": 4, "not_reachable": 1, "reachable_percent": 80 },
  "results": [
    { "provider": "Virgin Media", "provider_asn": 5089, "reachable": true,
      "stage": "http", "latency_ms": 412, "http_status": 200,
      "feedback": "Reached port 8080 from Virgin Media in GB in 412 ms, HTTP 200" },
    { "provider": "Sky Broadband", "provider_asn": 5607, "reachable": false,
      "stage": "connect", "error": "timed out after 15s",
      "feedback": "Not reached from Sky Broadband in GB: timed out after 15s" }
  ]
}

One entry in results per ISP tested. Poll while status is queued or running; the final status is done or failed (a failed check carries the reason in message). Results don't expose any internal hostnames.

Your plan & what's testable

GET /api/v1/me          # your plan, checks used this month and how many remain
GET /api/v1/countries   # countries you're allowed to test
GET /api/v1/providers?country=GB   # the ISPs tested for a country (name + ASN)

Errors

Every error is a JSON body with an error string.

400  bad input (e.g. ip isn't a public address, or country not allowed)
401  missing or invalid API key
402  monthly check limit reached   (includes "resets" date)
403  account paused
429  too many requests, slow down

curl example

curl -s https://ip.builtforyou.dev/api/v1/checks \
  -H "X-API-Key: rc_your_key_here" -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.10","port":443,"protocol":"https","country":"GB"}'

ReachCheck ยท reachability from real residential networks.