Poll a federation directory now
POST /admin/federation/directories/{id}/poll
Fetches the directory’s listing now instead of waiting for the background poller. Use it after subscribing, or whenever you want fresh entries.
Your instance checks that the listing is aa-directory/v1 and
signed with the operator key saved when you subscribed. If it is,
the cached entries are replaced with the ones fetched. Only the
first page of the listing is fetched, so a cached instance missing
from that page is removed, whether the directory dropped it or just
lists it on a later page. If anything fails, the cached entries stay
as they were.
Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Responses
Section titled “ Responses ”The subscription after the poll. A failed poll also returns 200, so check directory.last_poll_status (ok on success) and directory.last_poll_error.
object
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.
How many cached entries your instance read back after the poll. It isn’t the size of the directory.
Authentication 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