Subscribe to a federation directory
POST /admin/federation/directories
Subscribes your instance to a directory, so you can browse its
listing with GET /admin/federation/directories/{id}/entries.
Send the directory’s base URL, such as https://directory.example.
A trailing slash is dropped; a URL that isn’t https or that has a
path is refused with 400. Before saving anything, your instance
fetches /v1/operator from that URL and keeps the operator’s public
key with the subscription. From then on, a listing is accepted only
if it’s signed with that key.
Your instance trusts whatever key that first fetch returns. To check
it, compare operator_public_key with a copy you get from the
directory’s operator another way. If the directory changes its key
later, polls fail with signature_failed until you unsubscribe and
subscribe again.
A new subscription has no entries yet. Poll it with POST /admin/federation/directories/{id}/poll, or wait for the background
poller, which looks for directories to poll every five minutes.
You get 400 with the reason if the directory can’t be reached or
doesn’t report aa-directory/v1, and 409 if your instance already
subscribes to that URL. Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The directory’s base URL: https and a host name, with no path. For example, https://directory.example.
Responses
Section titled “ Responses ”Subscribed. The new subscription hasn’t been polled yet.
One directory your instance subscribes to: the operator key saved when you subscribed, how the last poll went and, if you’ve asked to be listed there, where your instance’s listing stands.
object
The directory operator’s Ed25519 public key in PEM, as the directory reported it when you subscribed. Polls accept only listings signed with this key.
The fingerprint the directory reported for its key when you subscribed. Your instance doesn’t check it against operator_public_key.
How the most recent poll went: ok, or why it failed. unreachable covers connection errors and any HTTP status other than 200, and signature_failed means the listing’s signature didn’t verify against operator_public_key. It’s never_polled until the first poll.
What went wrong in the most recent poll. Empty when it succeeded or there hasn’t been one.
How often the background poller refreshes this directory, in seconds. New subscriptions get 21600 (six hours), and the API can’t change it.
Where your instance’s listing in this directory stands, as your instance last recorded it: not_published until you request a challenge, then pending_dns, then listed or failed. It isn’t checked against the directory, so it can still say listed after the directory removes the listing. pending_register isn’t used.
Why the last attempt to list your instance didn’t go through. Cleared when you request a new challenge or the listing succeeds.
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 completedAlready subscribed to this directory URL.
object
Human-readable error summary
Example
the request could not be completed