Reachability API¶

The Reachability API provides active network probing data from distributed probe locations.

Configuration Required

The reachability endpoints require the PROBES_DATA KV namespace to be configured. If not configured, endpoints return a 503 error.

GET /reachability¶

Returns reachability status for all monitored targets.

Response¶

{
  "statuses": [
    {
      "targetId": "cloudflare-dns",
      "target": "1.1.1.1",
      "name": "Cloudflare DNS",
      "lastUpdated": "2025-01-15T12:00:00Z",
      "reachabilityPct": 100,
      "avgLatencyMs": 15,
      "minLatencyMs": 12,
      "maxLatencyMs": 25,
      "probeCount": 60,
      "successCount": 60,
      "regions": [
        {
          "region": "SJC",
          "reachable": true,
          "latencyMs": 15,
          "lastProbe": "2025-01-15T12:00:00Z",
          "successRate": 100
        }
      ],
      "trend": "stable"
    }
  ],
  "summary": {
    "totalTargets": 6,
    "highPriorityTargets": 3,
    "normalPriorityTargets": 3,
    "healthyTargets": 6,
    "degradedTargets": 0,
    "unreachableTargets": 0
  }
}

Example¶

curl https://ods-api.m-8b1.workers.dev/reachability

GET /reachability/:targetId¶

Returns detailed reachability status for a specific target.

Path Parameters¶

Parameter	Description
`targetId`	Target identifier (e.g., `cloudflare-dns`)

Response¶

Returns a single ReachabilityStatus object.

Example¶

curl https://ods-api.m-8b1.workers.dev/reachability/cloudflare-dns

POST /reachability/probe¶

Triggers an on-demand probe of specified or all targets.

Request Body¶

{
  "targetIds": ["cloudflare-dns", "google-dns"]
}

If targetIds is omitted, all targets are probed.

Response¶

{
  "region": "SJC",
  "duration": 1250,
  "results": [
    {
      "targetId": "cloudflare-dns",
      "target": "1.1.1.1",
      "timestamp": "2025-01-15T12:00:00Z",
      "region": "SJC",
      "probeType": "http",
      "reachable": true,
      "latencyMs": 15,
      "statusCode": 200
    }
  ]
}

Example¶

curl -X POST https://ods-api.m-8b1.workers.dev/reachability/probe \
  -H "Content-Type: application/json" \
  -d '{"targetIds": ["cloudflare-dns"]}'

GET /reachability/targets¶

Lists all configured probe targets.

Response¶

{
  "targets": [
    {
      "id": "cloudflare-dns",
      "name": "Cloudflare DNS",
      "type": "ip",
      "target": "1.1.1.1",
      "priority": "high",
      "asn": "AS13335"
    }
  ]
}

POST /reachability/targets¶

Adds a new probe target.

Request Body¶

{
  "id": "my-service",
  "name": "My Service",
  "type": "url",
  "target": "https://api.myservice.com/health",
  "priority": "high"
}

Required Fields¶

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Human-readable name
`type`	string	`"ip"`, `"hostname"`, or `"url"`
`target`	string	IP address, hostname, or URL to probe

Optional Fields¶

Field	Type	Default	Description
`priority`	string	`"normal"`	`"high"` (1/min) or `"normal"` (1/10min)
`asn`	string	-	Associated ASN
`regions`	string[]	-	Specific regions to probe from

DELETE /reachability/targets/:targetId¶

Removes a probe target.

Example¶

curl -X DELETE https://ods-api.m-8b1.workers.dev/reachability/targets/my-service

Trend Values¶

The trend field indicates reachability changes:

Value	Description
`improving`	Reachability increasing or latency decreasing
`stable`	No significant changes
`degrading`	Reachability decreasing or latency increasing
`unknown`	Insufficient data