Skip to content

Ask a directory to list your instance

POST
/admin/federation/directories/{id}/publish/register

The second step of listing your instance in a directory: call it once you’ve requested a challenge and added the DNS TXT record it gave you.

Your instance saves the details you send on the subscription, then sends them to the directory with the challenge token and your instance’s public key. The directory checks the DNS record; your instance doesn’t check it first.

Read publish_status in the response:

  • listed: the directory accepted the listing.
  • pending_dns: the directory couldn’t see the DNS record yet, and publish_last_error has its message. Wait for DNS to update, then call this again. The same challenge works until it expires.
  • failed: the directory refused the listing or couldn’t be reached, and publish_last_error says why. Request a new challenge with POST /admin/federation/directories/{id}/publish/challenge before you try again.

All three come back with 200. You get 400 if there’s no challenge waiting (publish_status isn’t pending_dns), if the challenge has expired, or if your instance has no base URL or its federation key isn’t available.

Listings and DNS records are public. Being listed lets other instances find yours; it doesn’t pair you with them or share anything.

Needs the system.admin capability.

id
required
string format: uuid

How your instance should appear in the directory’s listing. Your instance saves it on the subscription, so it’s still there for the next attempt.

object
display_name
required
string
>= 1 characters <= 200 characters
region
string
<= 100 characters
description
string
<= 2000 characters
tags
Array<string>
<= 20 items

The subscription, with the outcome in publish_status and publish_last_error.

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed