Instance & Server

This page covers the APIs for fetching server metadata, custom emojis, announcements, health status, user preferences, the profile directory, oEmbed embeds, and timeline markers.

Instance information

Current instance (v2)

final instance = await client.instance.fetch();
print(instance.title);
print(instance.description);
print(instance.version);

Returns a MastodonInstance with full v2 metadata including configured languages, rules, and contact information.

Version-dependent capabilities

Use detectCapabilities() before offering features that were added in newer Mastodon releases:

final capabilities = await client.instance.detectCapabilities();

switch (capabilities.supportFor(MastodonCapability.collections)) {
  case MastodonCapabilitySupport.supported:
    // Offer collection features.
  case MastodonCapabilitySupport.unsupported:
    // Hide or disable collection features.
  case MastodonCapabilitySupport.unknown:
    // Use a conservative fallback or let the user try the operation.
}

Capability	Server feature	Minimum Mastodon	API surface level
tagFeaturing	Feature or unfeature a tag	4.4.0	6
annualReportDetails	Fetch an annual report by year	4.4.0	6
oauthUserInfo	OpenID Connect UserInfo endpoint	4.4.0	6
asyncRefreshes	Check the status of an experimental async refresh operation	4.4.0	6
quotePosts	Quote-post operations	4.5.0	7
collections	Collections endpoints	4.6.0	10
donationCampaigns	Donation campaign endpoint	4.6.0	10
editableProfile	Fetch or update the editable profile	4.6.0	10
annualReportGeneration	Generate a report or fetch its state	4.6.0	10

Detection follows these rules:

1. Fetch GET /api/v2/instance and prefer api_versions.mastodon.
2. If that field is absent, parse the leading major.minor.patch from MastodonInstance.version as a best-effort fallback.
3. If the v2 endpoint itself returns 404, fetch the legacy GET /api/v1/instance endpoint and use its version string. Other errors are propagated without falling back.
4. Report unknown for a capability when the available metadata cannot be interpreted.

Cache the result once per server for the lifetime of the app process rather than requesting instance metadata before every API call.

api_versions.mastodon describes the API surface, not the Mastodon release. Its value can increase in a patch release or for a change that does not add a route, remain unchanged across multiple releases, and skip integers. Use only the lower-bound checks in the table; do not convert the value back into a Mastodon release.

Capability results are advisory. Forks and compatible implementations may not match their advertised metadata, so still handle errors from the actual API call. In particular, a 404 response is not guaranteed to distinguish a missing endpoint from a missing resource.

Peer domains

final peers = await client.instance.fetchPeers();
// List<String> of known federated domains

Weekly activity

final activity = await client.instance.fetchActivity();
for (final week in activity) {
  print('Statuses: ${week.statuses}');
}

Returns up to 12 weeks of MastodonWeeklyActivity objects.

Instance rules

final rules = await client.instance.fetchRules();
for (final rule in rules) {
  print(rule.text);
}

Domain blocks

final blocked = await client.instance.fetchDomainBlocks();

Returns the list of domains the instance has blocked. This is a server-level list, not the per-user list; see the Moderation page for user-level domain blocks.

Extended description

final description = await client.instance.fetchExtendedDescription();
print(description.content);

Privacy policy and terms of service

final policy = await client.instance.fetchPrivacyPolicy();
final tos = await client.instance.fetchTermsOfService();

// Fetch a specific historical version of the ToS by date
final old = await client.instance.fetchTermsOfServiceByDate('2024-01-01');

Translation languages

final languages = await client.instance.fetchTranslationLanguages();
// Map<String, List<String>> — source lang → supported target langs
languages.forEach((source, targets) {
  print('$source → $targets');
});

Legacy v1 (deprecated)

// ignore: deprecated_member_use
final instanceV1 = await client.instance.fetchV1();

fetchV1() is deprecated as of Mastodon 4.0.0. Prefer fetch() unless you need to support older servers.

---

Custom emojis

final emojis = await client.customEmojis.fetch();
for (final emoji in emojis) {
  print(':${emoji.shortcode}: → ${emoji.url}');
}

No authentication is required. Returns a List<MastodonCustomEmoji> of all custom emojis available on the server.

---

Announcements

Listing announcements

final announcements = await client.announcements.fetch();
for (final a in announcements) {
  print(a.text);
}

Dismissing an announcement

await client.announcements.dismiss('announcement-id');

Marks the announcement as read for the authenticated user.

Reactions

// Add a reaction (Unicode emoji or custom shortcode)
await client.announcements.addReaction('announcement-id', '👍');
await client.announcements.addReaction('announcement-id', 'blobcat');

// Remove a reaction
await client.announcements.removeReaction('announcement-id', '👍');

---

Health check

final healthy = await client.health.check();
// Returns true if the web process, database, and cache are all healthy.
// Throws MastodonException if any component is unhealthy.

No authentication is required. Useful for monitoring and readiness probes.

---

User preferences

final prefs = await client.preferences.fetch();
print(prefs.postingDefaultVisibility);
print(prefs.postingDefaultLanguage);
print(prefs.expandSpoilers);

Returns the authenticated user's MastodonPreferences. To update preferences, use client.accounts.updateCredentials().

---

Profile directory

// Most recently active accounts (global)
final active = await client.directory.fetch(
  order: 'active',
  limit: 40,
);

// Newest local accounts only
final newLocal = await client.directory.fetch(
  order: 'new',
  local: true,
);

Parameters:

Parameter	Default	Max	Description
limit	40	80	Number of results
offset	—	—	Skip this many results
order	—	—	active or new
local	—	—	true for local accounts only

No authentication is required.

---

oEmbed

final embed = await client.oembed.fetch(
  'https://mastodon.social/@user/12345',
  maxwidth: 500,
);
print(embed.html);

Returns a MastodonOEmbed with the embeddable HTML for a status URL. No authentication is required.

---

Timeline markers

Markers let you persist a user's read position in the home timeline and notifications timeline across sessions and devices.

Fetching markers

final markers = await client.markers.fetch(['home', 'notifications']);
final home = markers['home'];
print(home?.lastReadId);

Pass a list containing 'home', 'notifications', or both. Returns an empty map if neither is specified.

Saving markers

final updated = await client.markers.save(
  homeLastReadId: '109876543210',
  notificationsLastReadId: '987654321',
);

At least one of homeLastReadId or notificationsLastReadId must be provided. If the server responds with 409 Conflict (write conflict from another device), retry the request.

// Retry on conflict example
Map<String, MastodonMarker> result;
while (true) {
  try {
    result = await client.markers.save(homeLastReadId: lastId);
    break;
  } on MastodonConflictException {
    // Small delay before retry
    await Future.delayed(const Duration(milliseconds: 500));
  }
}