Ask another instance to pair
POST /admin/federation/peers/initiate
Adds another instance to your peer list as pending_outbound and
sends it a signed pairing request (an offer) for its admin to
accept.
Give its address as https:// and a host, with no path. When the
other admin accepts, their reply marks the pair connected on your
side. If your peer list already has that address, you get the
existing row as it is, possibly already connected, and nothing is
sent: calling this again isn’t a retry.
A 201 means only that the row was saved. If sending fails with an
error, the error is written to the stored row’s notes, but this
response is made from the copy of the row taken before that, so it
doesn’t show it. Read the row again with GET /admin/federation/peers/{id} to see the latest notes.
As shipped, the offer doesn’t get through to another Artist Alley
instance (see POST /federation/peers/handshake), and that instance
may answer the wrong address with a web page, which counts as
delivered. To pair two Artist Alley instances today, add each one to
the other’s peer list with POST /admin/federation/peers, using the
key from its GET /federation/instance.
Pairing shares nothing by itself; content reaches a peer only once
you share it. Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The other instance’s address: https:// and a host, with no path. A trailing slash is removed.
A name for it in your peer list. Defaults to the address without
https://; you can rename it later.
Responses
Section titled “ Responses ”The row on your side, usually pending_outbound. If the address was already in your peer list, it’s that row unchanged. A 201 doesn’t mean the other instance got the offer.
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 completed