List federation peers
GET /admin/federation/peers
Lists the instances in your peer list, newest first: connected peers, disabled ones and pending pairing requests in both directions.
Each entry is your own stored record of that instance, not live
information from it. Peers are ordered by when they were added
(handshake_at). limit is 50 by default; anything below 1 counts
as 50 and anything above 500 as 500. There’s no paging, so with more
than 500 peers you can’t list the rest.
Needs the federation.read or system.admin capability.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Responses
Section titled “ Responses ”Your peers, up to limit.
object
An instance in your peer list, and where pairing with it stands. Pairing shares nothing by itself: content reaches a peer only once you share it with that peer.
object
The instance’s address, such as https://peer.example, with no path or trailing slash.
The instance’s Ed25519 public key, PEM-encoded. A row you created by
asking to pair holds the placeholder PENDING-HANDSHAKE-RESPONSE
instead; only a confirm from that instance replaces it with a real
key.
A label you can set. Nothing in this release acts on it.
A label you can set. Nothing in this release acts on it, so it doesn’t decide whether what you send this peer is encrypted.
When off, no new activity is queued for this peer, it isn’t asked for suggestions and it isn’t in your public list, whatever its status.
Where pairing stands on your side: pending_outbound (you asked to
pair), pending_inbound (it asked and waits for your approval) or
connected. It’s your instance’s own record, not a sign that the
other instance is reachable or has connected too. Activity is queued
only for peers that are connected and enabled.
When this row was created. It doesn’t change when the pair connects.
The user who added this peer or asked to pair; 0 when the row came from the other instance’s request.
Not recorded in this release, so it’s left out.
Free text you can edit. Pairing adds a dated line here when sending a request or reply fails.
Whether this peer appears in your public GET /federation/peers/visible list, which anyone can read. Off by
default. It’s listed only while it’s also connected and enabled.
Not filled in by this release: always 0001-01-01T00:00:00Z.
Not filled in by this release: always 0001-01-01T00:00:00Z.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed