Skip to content

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.

object
directory_url
required

The directory’s base URL: https and a host name, with no path. For example, https://directory.example.

string
notes
string

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
id
required
string format: uuid
directory_url
required
string
operator_name
required
string
operator_public_key
required

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.

string
operator_fingerprint
required

The fingerprint the directory reported for its key when you subscribed. Your instance doesn’t check it against operator_public_key.

string
operator_contact
string
subscribed_at
required
string format: date-time
subscribed_by_user_ref
required
integer format: int64
enabled
required
boolean
last_polled_at
string format: date-time
nullable
last_poll_status
required

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.

string
Allowed values: never_polled ok unreachable signature_failed malformed spec_version_mismatch
last_poll_error
required

What went wrong in the most recent poll. Empty when it succeeded or there hasn’t been one.

string
poll_interval_seconds
required

How often the background poller refreshes this directory, in seconds. New subscriptions get 21600 (six hours), and the API can’t change it.

integer
notes
required
string
publish_status

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.

string
Allowed values: not_published pending_dns pending_register listed failed
publish_pending_token
string
publish_token_expires_at
string format: date-time
nullable
publish_record_name
string
publish_record_value
string
publish_listing_id
string
publish_last_attempt_at
string format: date-time
nullable
publish_last_error

Why the last attempt to list your instance didn’t go through. Cleared when you request a new challenge or the listing succeeds.

string
publish_display_name
string
publish_region
string
publish_description
string
publish_tags
Array<string>

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

Already subscribed to this directory URL.

object
error
required

Human-readable error summary

string
Example
the request could not be completed