API Reference

Endpoint

Returns a list of all known public peers, with optional filtering.

Query parameters

All parameters are optional and can be combined freely.

Response format

The response is a JSON object with metadata and a peers array. Counts reflect the filtered result set, not the full database.

Breaking contract change: JSON and CSV replace the old boolean reachability field with status and explicit freshness and distributed-probe coverage. Unknown never means offline.

{
  "updated_at":  "2025-01-01T12:00:00Z",  // time this response was generated (UTC)
  "window_days": 7,                        // uptime window used for uptime_pct
  "total":       142,                      // total peers in this response
  "online":      98,                       // peers currently reachable
  "offline":     30,                       // all eligible probes reported failure
  "unknown":     14,                       // incomplete, missing, or expired evidence
  "peers": [
    {
      "uri":              "tls://example.com:8001",  // full connection URI
      "country":          "DE",
      "protocol":         "tls",
      "host":             "example.com",
      "port":             8001,
      "status":           "up",            // up, down, or unknown
      "is_network":       false,           // true for overlay network peers
      "state_changed_at": "2025-01-01T11:30:00Z",  // last effective status change, including expiry (or null)
      "last_checked_at":  "2025-01-01T11:59:00Z",  // server measurement time (or null)
      "status_valid_until": "2025-01-01T12:06:00Z", // expiry (or null)
      "last_round_id":    42,              // published measurement round (or null)
      "successful_probes": 2,              // successful probes in that round
      "reporting_probes":  3,              // eligible probes reporting
      "expected_probes":   3,              // eligible probes expected
      "registered_probes": 4,              // registered enabled probes in the round
      "uptime_pct":       98.21,           // known rounds up / all known rounds (or null)
      "coverage_pct":     92.50            // known rounds / all rounds (or null)
    },
    ...
  ]
}

Examples

Bulk export

If you need a one-off snapshot of all peers without filtering, two export formats are available:

CSV has one row per peer with the same scalar fields as JSON. Optional timestamps, round IDs, and percentages are blank when absent. Probe counts are snapshots of the published round, not the current registry.

The CSV response includes two response headers carrying the metadata that the JSON envelope provides inline:

HTTP status codes

Notes

• Distributed probes check reachability in scheduled rounds. A check succeeds only when the peer URI answers with a valid Yggdrasil handshake matching any key pin. up requires at least one success; down requires all eligible reports to be failures. Missing reports and expired measurements are unknown.
• The uptime_pct field excludes unknown rounds. coverage_pct includes them in its denominator. Legacy history is single-location data without per-probe attribution.
• registered_probes is frozen for the round. expected_probes excludes probes ineligible for that peer; reporting_probes counts received eligible reports. See the peer page for regional successes, failures, and missing reports.
• Peers listed with is_network: true are hosted inside overlay networks (e.g. accessed via another Yggdrasil node) and may not be reachable from the public internet.
• Peer data is sourced from the yggdrasil-network/public-peers repository and refreshed periodically.
• Error responses use the same application/json content type as successful responses, with the shape {"error": "..."}.