Skip to content

List suggested peers

GET
/admin/federation/suggestions

Lists the suggestions your instance has saved from your peers’ public lists, each with the peer that listed it.

The list comes from your instance’s saved copy, newest first; only POST /admin/federation/suggestions/refresh updates it. Addresses already in your peer list are hidden, checked against up to 500 of your peer records, so with more peers than that a known instance can still appear. limit (200 by default) is applied before that filter, so you can get fewer. An instance listed by two of your peers appears once for each.

A suggestion is only a hint: its address, name, key and fingerprint are as your peer reported them, unchecked. Pairing with one is a separate step (see POST /admin/federation/peers/initiate).

Needs the federation.read or system.admin capability.

limit
integer
default: 200 >= 1 <= 500

List of suggestions.

object
items
required
Array<object>

An instance one of your peers shows publicly, with the peer that listed it. Its address, name, key and fingerprint are as that peer reported them, unchecked.

object
id
required
string format: uuid
source_peer_id
required
string format: uuid
source_display_name
required
string
source_url
required
string
suggested_url
required
string
suggested_display_name
required
string
suggested_public_key
required
string
suggested_fingerprint
required

As the peer reported it. It isn’t checked against suggested_public_key.

string
cached_at
required

When this suggestion was last saved from that peer.

string format: date-time

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed