Entwickler # Mit Welley entwickeln Mit der Welley-API kannst du Clients, Skripte, Community-Tools und Integrationen bauen. Die Live-Swagger-Referenz beschreibt die Operationen und Schemas, die du nutzen kannst. [Live-Swagger-UI öffnen](https://welley.social/q/swagger-ui/) [OpenAPI-JSON herunterladen](https://welley.social/q/openapi?format=json) Wir planen, Welley in Zukunft als Open Source zu veröffentlichen. Einen Veröffentlichungstermin und eine Lizenz haben wir noch nicht bekannt gegeben. ## Mit einer öffentlichen Anfrage beginnen Die API läuft über HTTPS, und die meisten Operationen nehmen JSON entgegen und geben JSON zurück. Öffentliche Leseoperationen funktionieren auch ohne Konto. ### Serverinformationen lesen Diese Anfrage liefert öffentliche Metadaten zum Server. Sie ändert keine Serverdaten. ``` curl --fail --silent --show-error "https://welley.social/api/v1/instance" ``` ### Die Operation in Swagger nachschlagen Bevor du einen Client schreibst, prüfe die Parameter, das Anfrageschema, das Antwortschema und die Berechtigungen der Operation. ## Eine Integration authentifizieren Geschützte Operationen brauchen ein gültiges Token im Authorization-Header. Unsere offizielle CLI sendet das Token mit dem Präfix Bearer. ### Deine effektiven Serverberechtigungen lesen Setze WELLEY\_TOKEN auf dein eigenes gültiges Token, so wie du üblicherweise mit Geheimnissen umgehst. Dieses Beispiel liest nur Daten. ``` curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions" ``` - Erstelle für eine Integration in deinen Kontoeinstellungen ein persönliches Zugriffstoken. - Gib ihm einen Namen und ein Ablaufdatum. Die API akzeptiert auch expiresInDays=0 für ein Token ohne gespeichertes Ablaufdatum. - Begrenze, welche globalen Berechtigungen, Gruppenberechtigungen und Gruppen das Token nutzen kann. - Wenn du eine Positivliste leer lässt, wird dieses Feld nur durch deinen aktuellen Zugriff begrenzt. Ein Token kann keine Rechte geben, die du nicht hast. - Das Token-Geheimnis siehst du nur einmal. Speichere es, bevor du das Ergebnis der Erstellung schließt. - Um Tokens zu verwalten, brauchst du eine Anmeldesitzung für dein Konto. Mit einem persönlichen Zugriffstoken kannst du Tokens weder erstellen noch auflisten, kopieren oder widerrufen. ## Berechtigungen und Geltungsbereich prüfen Die Authentifizierung sagt der API, wer anfragt. Rollenberechtigungen entscheiden, welche Operationen der Aufrufer nutzen kann. - Die API gibt 401 zurück, wenn eine geschützte Anfrage keine gültige Authentifizierung hat. - Die API gibt 403 zurück, wenn dem Aufrufer eine erforderliche Berechtigung fehlt. - Berechtigungsnamen folgen dem Muster Resource.Action, zum Beispiel GroupSettings.Manage. - Lass bei Webhook- und Berechtigungsoperationen mit Geltungsbereich scope weg, um den Serverbereich zu nutzen. Für den Gruppenbereich gib die TypeId der Gruppe an. - Lies die Beschreibung jeder Operation. Manche Endpunkte nutzen HTTP-Signaturen oder ein anderes Protokoll statt eines Kontotokens. ## Einen API-Bereich wählen Die Referenz deckt soziale Funktionen, Integrationen und Serveradministration ab. Die Beispiele hier zeigen nur einen kleinen Teil der API. ### Konten und Profile Lies Profile, verwalte die Identitäten eines Kontos und nutze die Operationen zum Exportieren oder Umziehen eines Kontos. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | GET | `/api/v1/users` | Lies ein lokales oder externes Profil anhand des Nutzernamens. | Öffentlich oder mit optionalem Token | | POST | `/api/v1/users` | Füge dem aktuellen Konto ein weiteres Profil hinzu, bis zum Limit des Servers. | Token erforderlich | ### Beiträge und Feeds Lies Feeds und erstelle Beiträge. Für Antworten, Umfragen, Reaktionen, Entwürfe und gespeicherte Beiträge gibt es weitere Operationen. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | GET | `/api/v1/posts` | Lies öffentliche Beiträge als Gast oder einen personalisierten Feed, wenn du authentifiziert bist. | Öffentlich oder mit optionalem Token | | POST | `/api/v1/posts` | Erstelle einen Beitrag mit seinem Inhalt und lege fest, wer ihn sehen kann. | Token erforderlich | ### Gruppen und Veranstaltungen Baue Community-Tools mit Gruppen, Mitgliedschaft, Kanälen, Moderation und Veranstaltungen. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | POST | `/api/v1/groups` | Erstelle eine Gruppe mit den Berechtigungen des authentifizierten Nutzers. | Token erforderlich | | GET | `/api/v1/events` | Liste öffentliche Veranstaltungen oder die Veranstaltungen auf, die der authentifizierte Nutzer sehen kann. | Öffentlich oder mit optionalem Token | | POST | `/api/v1/events` | Erstelle eine Veranstaltung. Für eine Gruppenveranstaltung ist GroupEvents.Create nötig. | Token erforderlich | ### Unterhaltungen und Benachrichtigungen Lies Unterhaltungsräume und ihre Nachrichten. Lies Benachrichtigungssammlungen und aktualisiere, ob sie gelesen sind. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | GET | `/api/v1/rooms` | Liste die Räume des aktuellen Nutzers auf. Um die Liste fortzusetzen, nutze nextCursor aus dem Antwortbody. | Token erforderlich | | GET | `/api/v1/user-notifications` | Liste die Benachrichtigungen des aktuellen Nutzers auf. | Token erforderlich | ### Medien, Suche und Übersetzung Lade Medien hoch, durchsuche die Inhalte, die du sehen kannst, und fordere Textübersetzungen an. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | POST | `/api/v1/uploads` | Erstelle einen Upload-Eintrag und sende den Dateiinhalt dann per PUT an die zurückgegebene Upload-URL. | Token erforderlich | | GET | `/api/v1/search` | Durchsuche die Inhalte, die der Aufrufer sehen kann, oder löse unterstützte URLs auf. | Öffentlich oder mit optionalem Token | | POST | `/api/v1/translate/text` | Übersetze Text in die gewünschte Sprache. | Token erforderlich | ### Webhooks und KI-Agenten Verbinde externe Dienste über Webhooks. Richte KI-Agenten über die Agenten-APIs ein. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | GET | `/api/v1/webhooks/events` | Ruf die Liste der unterstützten Webhook-Ereignistypen ab. | Token erforderlich | | POST | `/api/v1/webhooks` | Erstelle einen Webhook in einem Server- oder Gruppenbereich, für den du die Berechtigung hast. Das HTTP-Signaturgeheimnis wird nur einmal angezeigt. | Token erforderlich | | GET | `/api/v1/ai-agents` | Liste die KI-Agenten auf, die der Aufrufer sehen kann. | Token erforderlich | ### Server- und Gruppenadministration Nutze die API für Einstellungen, Meldungen, Moderation, Föderationssteuerung, Kontingente und die Administration des Deployments. | Methode | Pfad | Operation | Zugriff | | --- | --- | --- | --- | | GET | `/api/v1/rbac/permissions` | Lies die effektiven Berechtigungen für den aktuellen Nutzer und Bereich. | Token erforderlich | | GET | `/api/v1/settings` | Lies die Plattformeinstellungen, wenn das Konto die nötigen Berechtigungen hat. | Öffentlich oder mit optionalem Token | ## API-Antworten und Medien verarbeiten Folge dem eigenen Paginierungs- und Upload-Ablauf jeder Operation. - Folge bei Cursor-Feeds den Paginierungslinks, die der Server zurückgibt. Baue Cursor nicht aus Vermutungen über IDs. - Räume geben im Antwortbody einen opaken nextCursor zurück. Behalte beim Fortsetzen der Liste dieselben Filter bei. - Um Medien hochzuladen, erstelle einen Upload-Eintrag und sende den Inhalt dann an die zurückgegebene URL. - Prüfe die Fehlerantworten und Limits jeder Operation. Selbst eine dokumentierte Operation kann eine Rolle, eine Serverkonfiguration oder einen externen Anbieter voraussetzen.