Instanz & Server

Diese Seite behandelt die APIs zum Abrufen von Server-Metadaten, benutzerdefinierten Emojis, Ankündigungen, dem Gesundheitsstatus, Benutzereinstellungen, dem Profil-Verzeichnis, oEmbed-Einbettungen und Timeline-Markierungen.

Instanzinformationen

Aktuelle Instanz (v2)

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

Gibt eine MastodonInstance mit vollständigen v2-Metadaten zurück, einschließlich konfigurierter Sprachen, Regeln und Kontaktinformationen.

Versionsabhängige Funktionen

Verwenden Sie detectCapabilities(), bevor Sie Funktionen anbieten, die erst in neueren Mastodon-Versionen hinzugefügt wurden:

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

switch (capabilities.supportFor(MastodonCapability.collections)) {
  case MastodonCapabilitySupport.supported:
    // Sammlungsfunktionen anbieten.
  case MastodonCapabilitySupport.unsupported:
    // Sammlungsfunktionen ausblenden oder deaktivieren.
  case MastodonCapabilitySupport.unknown:
    // Konservativen Fallback verwenden oder den Versuch zulassen.
}

Capability	Serverfunktion	Mindestversion	API-Oberflächenstand
tagFeaturing	Tag hervorheben oder nicht mehr hervorheben	4.4.0	6
annualReportDetails	Jahresbericht nach Jahr abrufen	4.4.0	6
oauthUserInfo	OpenID-Connect-Benutzerinfo	4.4.0	6
asyncRefreshes	Experimenteller Status asynchroner Aktualisierungen	4.4.0	6
quotePosts	Operationen für Zitatbeiträge	4.5.0	7
collections	Sammlungs-Endpunkte	4.6.0	10
donationCampaigns	Spendenkampagnen-Endpunkt	4.6.0	10
editableProfile	Bearbeitbares Profil abrufen oder aktualisieren	4.6.0	10
annualReportGeneration	Bericht erzeugen oder Status abrufen	4.6.0	10

Die Erkennung folgt diesen Regeln:

1. GET /api/v2/instance abrufen und api_versions.mastodon bevorzugen.
2. Fehlt das Feld, den führenden Wert major.minor.patch aus MastodonInstance.version als Best-Effort-Fallback auswerten.
3. Antwortet der v2-Endpunkt selbst mit 404, den veralteten Endpunkt GET /api/v1/instance abrufen und dessen Versionszeichenfolge verwenden. Andere Fehler werden ohne Fallback weitergegeben.
4. unknown zurückgeben, wenn die Metadaten nicht ausgewertet werden können.

Cachen Sie das Ergebnis einmal pro Server für die Laufzeit des App-Prozesses, anstatt die Instanz-Metadaten vor jedem API-Aufruf neu anzufordern.

api_versions.mastodon bezeichnet einen API-Oberflächenstand und keine Releaseversion. Der Wert kann in Patch-Releases oder durch Änderungen ohne neue Route steigen, von mehreren Releases geteilt werden und Ganzzahlen überspringen. Verwenden Sie nur die Untergrenzen der Tabelle und leiten Sie daraus keine Mastodon-Releaseversion ab.

Die Ergebnisse dienen nur als Orientierung. Forks und kompatible Implementierungen können von ihren gemeldeten Metadaten abweichen. Behandeln Sie deshalb weiterhin Fehler des tatsächlichen API-Aufrufs. Insbesondere unterscheidet eine 404-Antwort nicht zuverlässig zwischen einem fehlenden Endpunkt und einer fehlenden Ressource.

Bekannte Domains (Peers)

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

Wöchentliche Aktivität

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

Gibt bis zu 12 Wochen an MastodonWeeklyActivity-Objekten zurück.

Instanzregeln

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

Domain-Sperren

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

Gibt die Liste der von der Instanz gesperrten Domains zurück. Dies ist eine serverweit geltende Liste, nicht die benutzerspezifische; für benutzerspezifische Domain-Sperren siehe die Seite Moderation.

Erweiterte Beschreibung

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

Datenschutzrichtlinie und Nutzungsbedingungen

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');

Übersetzungssprachen

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

Veraltetes v1

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

fetchV1() ist seit Mastodon 4.0.0 veraltet. Verwende fetch(), außer wenn ältere Server unterstützt werden müssen.

---

Benutzerdefinierte Emojis

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

Keine Authentifizierung erforderlich. Gibt eine List<MastodonCustomEmoji> aller auf dem Server verfügbaren benutzerdefinierten Emojis zurück.

---

Ankündigungen

Ankündigungen auflisten

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

Ankündigung schließen

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

Markiert die Ankündigung für den authentifizierten Benutzer als gelesen.

Reaktionen

// 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', '👍');

---

Gesundheitsprüfung

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.

Keine Authentifizierung erforderlich. Nützlich für Monitoring und Readiness-Prüfungen.

---

Benutzereinstellungen

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

Gibt die MastodonPreferences des authentifizierten Benutzers zurück. Zum Aktualisieren der Einstellungen client.accounts.updateCredentials() verwenden.

---

Profil-Verzeichnis

// 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,
);

Parameter:

Parameter	Standard	Max	Beschreibung
limit	40	80	Anzahl der Ergebnisse
offset	—	—	Diese Anzahl an Ergebnissen überspringen
order	—	—	active oder new
local	—	—	true für nur lokale Accounts

Keine Authentifizierung erforderlich.

---

oEmbed

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

Gibt ein MastodonOEmbed mit dem einbettbaren HTML für eine Status-URL zurück. Keine Authentifizierung erforderlich.

---

Timeline-Markierungen

Markierungen ermöglichen es, die zuletzt gelesene Position eines Benutzers in der Home-Timeline und der Benachrichtigungs-Timeline sitzungs- und geräteübergreifend zu speichern.

Markierungen abrufen

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

Eine Liste mit 'home', 'notifications' oder beidem übergeben. Gibt eine leere Map zurück, wenn keines angegeben ist.

Markierungen speichern

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

Mindestens eines der Felder homeLastReadId oder notificationsLastReadId muss angegeben werden. Wenn der Server mit 409 Conflict antwortet (Schreibkonflikt durch ein anderes Gerät), die Anfrage wiederholen.

// 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));
  }
}