Skip to content

List a directory's cached entries

GET
/admin/federation/directories/{id}/entries

Lists the instances in this directory’s listing as of its last successful poll. They come from your instance’s own copy, so the list still works while the directory is down.

Entries the directory verified most recently come first. You get up to limit entries, 200 by default, with no paging.

Two things can make the list shorter than you expect. Your instance fetches only the first page of a directory’s listing, so a large directory can show fewer instances here than it lists. And the list is cached in memory: after a request with a smaller limit, a larger one can return the shorter list until the next successful poll.

Browsing doesn’t contact or pair with anyone. To pair with an instance you find here, start a handshake with POST /admin/federation/peers/initiate.

Needs the federation.read or system.admin capability.

id
required
string format: uuid
limit
integer
default: 200 >= 1 <= 500

Cached entries.

object
items
required
Array<object>

One instance from the directory’s listing, as cached at the last successful poll. Apart from id, directory_id and cached_at, the values are the directory’s, unchanged. Your instance checks the directory’s signature on the listing, not each instance.

object
id
required
string format: uuid
directory_id
required
string format: uuid
instance_url
required
string
display_name
required
string
instance_public_key
required
string
fingerprint
required
string
region
string
description
string
tags
Array<string>
verified_at
required
string format: date-time
verified_via
required
string
listing_id
string
cached_at
required
string format: date-time

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