Skip to content

Manually add a federation peer

POST
/admin/federation/peers

Adds another instance to your peer list with the address and Ed25519 public key you give, and marks it connected straight away. Nothing is sent to that instance.

This is how two Artist Alley instances pair today: each admin adds the other here. Copy instance_url and public_key_pem exactly from the other instance’s GET /federation/instance, and check the fingerprint with its admin. Incoming requests are matched to your list by that exact address, and the server checks only that the key is a valid PEM-encoded Ed25519 key, not whose it is. Until the other side adds yours, it refuses what you send.

instance_url must be https:// and a host with no path. Surrounding spaces and trailing slashes are removed and nothing else is changed, so a difference in letter case makes a different address. An address already in your list gets 409. The address is checked for shape only: the server doesn’t contact it or check where it points.

The peer is enabled unless you send "enabled": false. trust_tier and encryption_policy default to connected and plaintext; both are labels that nothing in this release acts on. No capabilities are exchanged with a peer added this way, so nothing you send it is encrypted.

Needs the system.admin capability.

object
instance_url
required

The other instance’s address, such as https://peer.example: https:// and a host, with no path. Trailing slashes are removed.

string
display_name
required
string
>= 1 characters <= 200 characters
instance_public_key
required

The other instance’s Ed25519 public key, PEM-encoded, as its GET /federation/instance gives it in public_key_pem. The server checks that it parses, not who it belongs to.

string
trust_tier
string
default: connected
Allowed values: connected directory-listed auto-sync
encryption_policy
string
default: plaintext
Allowed values: plaintext e2e-encrypted
enabled
boolean
default: true
notes
string

Peer created.

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
id
required
string format: uuid
instance_url
required

The instance’s address, such as https://peer.example, with no path or trailing slash.

string
display_name
required
string
instance_public_key
required

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.

string
trust_tier
required

A label you can set. Nothing in this release acts on it.

string
Allowed values: connected directory-listed auto-sync
encryption_policy
required

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.

string
Allowed values: plaintext e2e-encrypted
enabled
required

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.

boolean
status
required

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.

string
Allowed values: pending_outbound pending_inbound connected
handshake_at
required

When this row was created. It doesn’t change when the pair connects.

string format: date-time
handshake_by_user_ref
required

The user who added this peer or asked to pair; 0 when the row came from the other instance’s request.

integer format: int64
last_seen_at

Not recorded in this release, so it’s left out.

string format: date-time
nullable
notes
required

Free text you can edit. Pairing adds a dated line here when sending a request or reply fails.

string
share_in_visible_list

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.

boolean
created_at
required

Not filled in by this release: always 0001-01-01T00:00:00Z.

string format: date-time
updated_at
required

Not filled in by this release: always 0001-01-01T00:00:00Z.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Peer with this instance_url already exists.

object
error
required

Human-readable error summary

string
Example
the request could not be completed