Edit a federation peer
PATCH /admin/federation/peers/{id}
Changes the settings you keep for a peer: display_name,
trust_tier, encryption_policy, enabled, notes and
share_in_visible_list. Only the fields you send change.
A field you leave out, or send as null, keeps its value.
display_name and notes are free text, so an empty string is
stored as given: "notes": "" clears the notes. The address, key
and status can’t be changed here. To use a different address or
key, delete the peer and add it again, which also deletes what’s
stored for it (see DELETE /admin/federation/peers/{id}).
With enabled off, your instance refuses deliveries from the peer,
and anything queued for it is marked failed when the worker
reaches it instead of being sent. Shares stay in place and nothing
already delivered is recalled. trust_tier and encryption_policy
are labels that nothing in this release acts on.
share_in_visible_list lists the peer in your public GET /federation/peers/visible only while it’s also connected and
enabled; it doesn’t publish it anywhere else or pair with anyone.
An unknown trust_tier or encryption_policy value gets 400 and an
unknown id gets 404. Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”Every field is optional. Leave a field out, or send it as null, to
keep its value.
object
Whether to show this peer in your public GET /federation/peers/visible list, which anyone can read.
Responses
Section titled “ Responses ”Updated peer.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication 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 completedResource not found
object
Human-readable error summary
Example
the request could not be completed