Yggdrasil Peers

Overview

The peers API is a read-only JSON API intended for Yggdrasil software developers and tools that need programmatic access to peer data. It returns the same data shown on the main page, with optional filtering by country, protocol, and status.

No authentication is required. All responses are application/json.

Endpoint

GET /api/v1/peers

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

Query parameters

All parameters are optional and can be combined freely.

Parameter	Type	Description
`country`	string	Filter by country name or ISO 3166-1 alpha-2 code. Case-insensitive (e.g. `germany`, `United States`, `de`, `US`).
`protocol`	string	Filter by protocol. Case-insensitive. One of: `tcp`, `tls`, `quic`, `ws`, `wss`, `socks`, `sockstls`.
`is_up`	boolean	Filter by current reachability. `true` returns only peers that are currently online; `false` returns only offline peers.
`is_network`	boolean	Filter by peer type. `false` returns regular public peers; `true` returns overlay network peers (e.g. Hyperboria).

Response format

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

{
  "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
  "peers": [
    {
      "uri":              "tls://example.com:8001",  // full connection URI
      "country":          "DE",
      "protocol":         "tls",
      "host":             "example.com",
      "port":             8001,
      "is_up":            true,            // currently reachable
      "is_network":       false,           // true for overlay network peers
      "state_changed_at": "2025-01-01T11:30:00Z",  // last up/down transition (or null)
      "uptime_pct":       98.21            // 7-day uptime percentage (or null if no data)
    },
    ...
  ]
}

Examples

All peers (no filter)

/api/v1/peers

Only peers currently online

/api/v1/peers?is_up=true

QUIC peers in Germany

/api/v1/peers?country=germany&protocol=quic

Online TLS peers, excluding overlay networks

/api/v1/peers?protocol=tls&is_up=true&is_network=false

Bulk export

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

All peers as JSON (same shape as the API, no filters)

/peers.json

All peers as CSV (column headers match JSON field names)

/peers.csv

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

Header	Example	Description
`X-Updated-At`	`2025-01-01T12:00:00Z`	Time the response was generated (UTC, RFC 3339).
`X-Window-Days`	`7`	Uptime window used for the `uptime_pct` column.

HTTP status codes

Status	Meaning
`200 OK`	Successful response. Body is JSON.
`400 Bad Request`	A query parameter has an invalid value. Body is `{"error": "..."}`.
`500 Internal Server Error`	Server-side failure. Body is plain text.

Notes

Peer reachability is checked every few minutes. Responses are cached for up to 30 seconds, so data may be slightly stale.
The uptime_pct field reflects the past window_days days. It is null for peers that were added recently and have not yet accumulated enough check history.
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": "..."}.