Offene Community-API

1. Der Tarif der Community muss API-Zugang enthalten

Darüber entscheidet die Person, der die Community gehört, nicht die integrierende Seite. Der Tarif braucht die Funktion API-Zugang — sonst gibt jeder Aufruf 22203 zurück — und ein Tageskontingent ungleich null, andernfalls gibt jeder Aufruf 22204 zurück.

Sie müssen das nicht über gesammelte Fehler herausfinden: /capabilities/get beantwortet es direkt und funktioniert auch in genau diesen beiden Fällen.

2. Einen Schlüssel in der Admin-Konsole der Community erstellen

Community-Verwaltung → Integrationen → API Keys → Erstellen. Ein Schlüssel besteht aus mfk_ gefolgt von 64 Hexadezimalzeichen, und der vollständige Wert wird genau einmal angezeigt — danach ist nur noch das Präfix sichtbar.

Die beim Anlegen gesetzten Scopes bestimmen, welche Endpunkte der Schlüssel aufrufen darf. Sie lassen sich später nicht ändern; erstellen Sie dafür einen neuen Schlüssel und widerrufen Sie den alten.

Optional können Sie einen Schlüssel auf eine IP-Freigabeliste beschränken (einzelne Adressen oder CIDR-Bereiche). Anfragen von anderswo scheitern mit 10007 — demselben Code wie bei einem ungültigen Schlüssel, was man sich merken sollte, wenn ein gestern noch funktionierender Schlüssel von einem neuen Host aus versagt.

Scopes

Ein älterer Schlüssel kann die neueren Endpunkte also nicht aufrufen — Spaces, Mitglieder und das Lesen signierter URLs. Stellen Sie einen neuen Schlüssel mit diesen Scopes aus. Das ist Absicht: Niemand sollte sein Mitgliederverzeichnis herausgeben, nur weil die Plattform eine neue Funktion veröffentlicht hat.

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

Der Schlüssel ist für sich genommen das Zugangsmittel — bewahren Sie ihn serverseitig auf. Er gehört weder in Browser-Code noch in ein Mobile-Bundle, wo ihn jeder auslesen und damit im Namen Ihrer Mitglieder posten kann.

• Jeder Endpunkt ist ein POST. Es gibt kein GET, PUT oder DELETE — auch Lesezugriffe sind POSTs.
• Senden Sie Content-Type: application/json. Endpunkte ohne Parameter erwarten trotzdem einen leeren JSON-Body.
• Jede ID ist ein Hashid-String wie "kZ3mQ9x" — für Community, Nutzer, Beitrag, Space und Medium gleichermaßen. Numerische IDs werden abgelehnt.
• Zeitstempel kommen als RFC3339 zurück, zum Beispiel 2026-08-18T10:00:00Z.
• Beträge sind Ganzzahlen in der kleinsten Währungseinheit (Cent).
• Ein optionaler Accept-Language-Header (zh, en, ja, ko, es, fr, de, pt) lokalisiert die Fehlermeldungen.
• Die Community wird aus Ihrem API-Schlüssel abgeleitet. Senden Sie keine Site-ID, weder im Pfad noch im Body.

Erfolg und Fehler teilen sich einen Umschlag

{
  "code": 0,
  "msg": "success",
  "data": { }
}

curl -X POST https://api.mateflow.com/site_open_api/v1/capabilities/get \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" -d '{}'

# → data: {
#     "api_version": "v1",
#     "site_id": "kZ3mQ9x",
#     "scopes": ["site.read", "content.read"],
#     "api_access": true,
#     "quota_limit": 5000,     // -1 means unlimited
#     "quota_used": 128,
#     "quota_reset_at": "2026-09-15T00:00:00Z"
#   }

• Lesezugriffe mit einer ID-Liste sind bei 50 gedeckelt, und limit ist bei allen paginierten Endpunkten ebenfalls bei 50 gedeckelt.
• Bei /space/feed/list folgt die Cursor-Kodierung dem sort-Wert; ein Sortierwechsel bedeutet also, die Paginierung neu zu beginnen. Q&A-Spaces ignorieren sort und ordnen stattdessen nach qa_sort. Neue Integrationen sollten /space/feed/list mit sort=top statt /space/feed/top verwenden.
• Mitgliederantworten sind eine schmale Projektion: id, username, display_name, avatar_url, status, role und created_at. Die E-Mail-Adresse wird nie zurückgegeben, auch dann nicht, wenn Sie darüber gesucht haben — Sie besitzen diese Adresse ohnehin, und die jedes Mitglieds zurückzuspiegeln würde /member/get in einen Adressbuch-Export verwandeln. Die Suche funktioniert nur bei exakter Übereinstimmung, und kein Treffer ist ein normaler Erfolg, kein Fehler: Treffer und Nicht-Treffer sind weder am Statuscode noch an der Antwortzeit zu unterscheiden. Auch die Ratenbegrenzung ist hier die strengste der gesamten API.

• author_user_id

  Das Mitglied, in dessen Namen ein neuer Beitrag erscheint. Es muss dieser Community bereits angehören, sonst 20303.

• actor_user_id

  Wer eine Bearbeitung oder Löschung ausführt. Die Rechte werden an diesem Mitglied geprüft — wer weder Verfasser noch Admin ist, erhält 10004.

• viewer_user_id

  Beim Lesen optional. Liefert die Ergebnisse so, wie dieses Mitglied sie sieht: private Spaces, Zustand von Likes und Lesezeichen. Weglassen ergibt die anonyme Sicht auf ausschließlich Öffentliches.

• Feeds und Listen liefern ihre Einträge samt next_cursor. Schicken Sie next_cursor unverändert zurück, um die nächste Seite zu holen; ein leeres next_cursor heißt, Sie sind am Ende angekommen.
• limit ist überall bei 50 gedeckelt.
• Bei /space/feed/list kodiert der Cursor die aktuelle Sortierung. Ein Sortierwechsel mitten in der Liste macht ihn ungültig — beginnen Sie wieder bei der ersten Seite.

• idempotency_key ist bei jedem Schreibzugriff Pflicht und auf 190 Zeichen begrenzt. Ihn wiederzuverwenden erzeugt nie einen zweiten Beitrag.
• Sein Gültigkeitsbereich ist die Kombination aus Community, Anfragetyp und Schlüsselwert, unabhängig davon, welchen API-Schlüssel Sie benutzt haben: Senden zwei verschiedene Schlüssel derselben Community denselben idempotency_key an denselben Endpunkt, gibt der zweite Aufruf das Ergebnis des ersten zurück.
• Derselbe Schlüssel mit einem anderen Body ergibt einen stabilen Konfliktfehler, statt stillschweigend als erfolgreicher Wiederholungsversuch durchzugehen.
• Läuft eine Anfrage in einen Timeout, wiederholen Sie sie mit demselben Schlüssel — erzeugen Sie niemals einen neuen.

• scheduled_at ist ein i64-Unix-Zeitstempel in Sekunden — nicht der RFC3339-String, den alle anderen Zeitangaben verwenden.
• Lassen Sie scheduled_at bei /post/update weg, bleibt die bestehende Terminierung unangetastet. Es ist kein Zurücksetzen.

1. Tauschen Sie Ihren API-Schlüssel über /media/get_token gegen ein kurzlebiges Upload-Token.
2. Senden Sie die Datei per multipart-POST an den Mediendienst, das Token in einem wörtlich "token" genannten Header und file_cate als Media, Avatar, Header, Audio oder File.
3. Übergeben Sie die zurückgegebene Medien-ID beim Anlegen des Beitrags in media_ids.

# 1. Exchange the API key for a short-lived upload token.
#    Since 2026-09 a token with no explicit scope is upload-only.
curl -X POST https://api.mateflow.com/site_open_api/v1/media/get_token \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id": "kZ3mQ9x", "scope": "upload"}'

# 2. Upload the file to the media service (token goes in a "token" header)
curl -X POST https://media.mateflow.com/api/v1/media/upload \
  -H "token: <token from step 1>" \
  -F "file_cate=Media" -F "file=@photo.jpg"

# 3. Attach the media id when creating the post
curl -X POST https://api.mateflow.com/site_open_api/v1/post/create \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id":"kZ3mQ9x","idempotency_key":"6f1c...","body":"Hi","media_ids":["m8Yq2Lp"]}'

Private Medien werden über /media/get_signed_urls gelesen. Der Endpunkt nimmt die items und ein access_level von 1 (öffentlich), 2 (halbprivat) oder 3 (privat) entgegen und liefert URLs mit Ablaufzeit. Fordern Sie sie bei Bedarf an, statt sie zu speichern, sonst liefern sie irgendwann 403.

Medien an einen Beitrag hängen

• Senden Sie entweder medias — eine Liste aus media_id und alt — oder media_ids, eine schlichte Liste von IDs. Beides zu senden ergibt 10005.
• alt ist optional. Ein leerer String löscht den vorhandenen Alternativtext; das Feld wegzulassen belässt ihn unverändert.

Fehlerantworten tragen eine request_id. Nennen Sie sie, wenn Sie ein Problem melden — darüber finden wir genau Ihren Aufruf in den Logs.

Tariffehler tragen strukturierte Metadaten

Beide Tariffehler kommen mit genug Details zurück, um der Eigentümerseite zu sagen, was zu tun ist — Sie können also eine echte Meldung zeigen statt „etwas ist schiefgelaufen“.

// The plan does not include API access
{
  "code": 22203,
  "msg": "...",
  "request_id": "00de5640-8ae5-4a71-aef8-2f2cab0ce8a7",
  "data": {
    "error_code": "feature_not_available",
    "feature": "api_access",
    "required_plan": "Growth"
  }
}

// The community is out of daily quota
{
  "code": 22204,
  "data": {
    "error_code": "quota_exceeded",
    "resource": "api_requests_per_day",
    "current": "5001",
    "limit": "5000",
    "required_plan": "Business"
  }
}

Das Tageskontingent zählt Anfragen, die die Authentifizierung passieren, wird um 00:00 UTC zurückgesetzt und meldet in data.limit die tatsächlich geltende Obergrenze — einschließlich einer eigens für diese Community angehobenen Freigabe. Wenn das Backend des Zählers Probleme macht, wird die Anfrage durchgelassen statt abgewiesen; eine gelegentliche Untererfassung heißt also nicht, dass das Kontingent nicht mehr greift.

Burst-Budget pro Schlüssel (neu im September 2026)

Früher gab es nur den Eimer pro IP: Mehrere Kunden hinter einer Ausgangsadresse machten sich gegenseitig Platz streitig, während ein über viele Adressen verteilter Aufrufer kaum eingeschränkt war. Das Budget ist nun pro Schlüssel gestaffelt — jenem Ding, das die Eigentümerseite ausstellt, rotieren kann und für das sie geradesteht.

member/lookup ist deutlich strenger — aus Sicherheitsgründen, nicht wegen der Kapazität. Die übrigen Beschränkungen begrenzen, wie viel eine einzelne Antwort preisgibt; diese begrenzt, wie oft Sie fragen dürfen — und genau das ist der Schritt, der aus einer Suche ein Abgrasen des Verzeichnisses macht. Für den vorgesehenen Zweck, nämlich bereits vorhandene Adressen im menschlichen Tempo aufzulösen, sind zehn pro Minute mehr als genug.

• Eine Überschreitung liefert HTTP 429 mit code 10202, dazu Retry-After sowie die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.
• Nehmen Sie diese Zahlen als Ausgangspunkt, nicht als Messwert — sie werden anhand des beobachteten Verkehrs angepasst. Verdrahten Sie sie nicht fest in Ihrer Retry-Logik; halten Sie sich an 429 und Retry-After. Die gesamte Ratenbegrenzung ist standardmäßig aus und läuft eine Weile im Beobachtungsmodus, bevor sie greift.
• Implementieren Sie in jedem Fall ein Backoff bei 429 und halten Sie den Leseverkehr bei etwa zehn Anfragen pro Sekunde oder darunter.

Entdoppeln Sie über event_id. Eine Zustellung, die Sie erfolgreich verarbeitet, aber zu langsam beantwortet haben, trifft erneut ein — mit neuer delivery_id und derselben event_id. Geht ein Ereignis gleichzeitig an einen eigenen Webhook und an einen Zap, sehen beide Seiten dieselbe event_id und lassen sich abgleichen.

Die Zustellung erfolgt mindestens einmal und kann in falscher Reihenfolge ankommen. Sowohl Duplikate als auch verspätet eintreffende ältere Ereignisse sind normal; die empfangende Seite muss idempotent sein.

• Die Community wird aus Ihrem API-Schlüssel abgeleitet. Senden Sie keine Site-ID, weder im Pfad noch im Body.
• Scopes stehen mit der Erstellung des Schlüssels fest. Zum Ändern erstellen Sie einen neuen Schlüssel und widerrufen den alten.
• Bewahren Sie Ihre API-Schlüssel serverseitig auf. Ein Schlüssel im Client-Code erlaubt jedem, der ihn liest, im Namen Ihrer Mitglieder zu posten.
• Der OpenAPI-Vertrag deckt jeden Pfad und jedes Schema ab. Ein Vorbehalt: Der Generator, aus dem er stammt, gibt kein required für Anfrage-Bodys aus — nehmen Sie die Pflichtfelder daher von dieser Seite und nicht aus dem Vertrag.