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.
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.