Skip to content
Artist Alley

List federation peers

GET
/admin/federation/peers

All paired instances, newest-handshake-first. Gated on system.admin. Per ADR 0043 §“Trust model” the rows here are just the trusted-channel registry — content shares are managed separately via federation_shares (Phase 1.22.C).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 50 >= 1 <= 500

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A page of peers.

object
items
required
Array<object>

One row from the federation_peers registry (Phase 1.22.B-a + ADR 0043 §“Trust model”). Pairing alone shares no content — see federation_shares (1.22.C) for the access-control layer.

object
id
required
string format: uuid
instance_url
required

Https://peer.example (no trailing slash, no path)

string
display_name
required
string
instance_public_key
required

PEM-wrapped Ed25519 public key (RFC 8410). May be the placeholder string PENDING-HANDSHAKE-RESPONSE while status is pending_outbound — the peer’s real key replaces it when the confirm envelope arrives.

string
trust_tier
required
string
Allowed values: connected directory-listed auto-sync
encryption_policy
required
string
Allowed values: plaintext e2e-encrypted
enabled
required
boolean
status
required

Handshake state machine (migration 00052 + v1.md §11). Outbound delivery (1.22.D) gates on connected only.

string
Allowed values: pending_outbound pending_inbound connected
handshake_at
required
string format: date-time
handshake_by_user_ref
required
integer format: int64
last_seen_at
string format: date-time
nullable
notes
required
string
share_in_visible_list

Per-peer opt-in for peer-of-peer discovery (Phase 1.22.B-d). When true, this peer appears in GET /federation/peers/visible — other peers can then surface it as a discovery suggestion. Default false; explicit opt-in.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time

401

Section titled “401 ”

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"
}

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed