Skip to content
FediDB.com

API documentation

Everything on FediDB comes from this API. It is public, read only and needs no key.

Overview

The base URL is https://api.fedidb.org/v1/. Responses are JSON. Most list endpoints page with a cursor and return at most the number of rows you ask for in limit. Totals are refreshed every 24 hours as each server is crawled.

Need everything at once? Download the weekly datasets instead of paging through the API.

Endpoints

GET

/v1/stats

Returns network statistics, updated every 15 minutes using the latest data we collect.

Request
curl -X GET "https://api.fedidb.org/v1/stats"
Response
GET

/v1/servers

Returns an array of ServerEntity

Query parameters for /v1/servers
ParameterTypeRequiredDescription
limitIntegerNoThe number of records to return, between 1-40. Default 10.
Request
curl -X GET "https://api.fedidb.org/v1/servers?limit=10"
GET

/v1/server/domain/{domain}

Endpoint is not cached. Returns a ServerEntity.

Query parameters for /v1/server/domain/{domain}
ParameterTypeRequiredDescription
domainstringYesThe domain name of the server.
Request
curl -X GET "https://api.fedidb.org/v1/server/domain/mastodon.social"
GET

/v1/software

Returns an array of SoftwareEntity

Query parameters for /v1/software
ParameterTypeRequiredDescription
limitIntegerNoThe number of records to return, between 1-40. Default 10.
Request
curl -X GET "https://api.fedidb.org/v1/software?limit=10"
GET

/v1/software/{slug}

Endpoint is cached for 15 minutes. Returns a SoftwareEntity.

Query parameters for /v1/software/{slug}
ParameterTypeRequiredDescription
slugstringYesThe slug identifier for the software.
Request
curl -X GET "https://api.fedidb.org/v1/software/pixelfed"

Entities

ServerEntity

A single server, as returned by the server endpoints.

Attributes of ServerEntity
AttributeTypeNullableDescription
idStringNoThe server id
domainStringNoThe server domain
open_registrationBooleanYesServer allows new account registration
descriptionStringYesDescription of the server
banner_urlStringYesURL of server banner image
location[city]StringYesThe city the server is hosted in
location[country]StringYesThe country the server is hosted in
software[id]IntegerYesThe server software id
software[name]StringYesThe server software name
software[url]StringYesThe server software FediDB listing URL
software[version]StringYesThe server software version
stats[status_count]IntegerYesThe total status count of this server
stats[user_count]IntegerYesThe total user count of this server
stats[monthly_active_users]IntegerYesThe monthly active users of the server
first_seen_atStringNoThe ISO8601 timestamp of when we first observed the server
last_seen_atStringYesThe ISO8601 timestamp of when we last observed the server
Example

SoftwareEntity

A software project, as returned by the software endpoints.

Attributes of SoftwareEntity
AttributeTypeNullableDescription
idStringNoThe software id
nameStringNoThe software name
urlStringNoThe url of the FediDB software listing
descriptionStringYesThe software description
licenseStringYesThe software license
instance_countIntegerNo
user_countIntegerNo
monthly_active_usersIntegerYes
status_countIntegerNo
websiteStringYes
source_repoStringYes
Example