Dokumentation der Loomio-Benutzer-API

/api/b2 ist die API für Integrationen, die im Namen eines Loomio-Benutzerkontos handeln. Sie verwendet dessen API-Schlüssel. Jede Aktion wird als dieser Benutzer ausgeführt.

Für Aktionen in Gruppen gelten die Mitgliedschaften und Gruppenberechtigungen des Benutzers, dessen API-Schlüssel verwendet wird. Administratorrechte für die Instanz erweitern den Zugriff des API-Schlüssels auf Gruppen oder Inhalte nicht. Verwende für die Verwaltung der Instanz die Server-API.

Verwende den API-Schlüssel des Loomio-Benutzerkontos, das die Aktionen ausführen soll. Ein eigenes Bot-Konto ist sinnvoll, wenn die Integration keine Einladungen zu Abstimmungen oder Benachrichtigungen erhalten soll.

Angemeldete Benutzer finden ihren API-Schlüssel und ihre Gruppen-IDs auf der Seite für den API-Zugriff.

Sende den API-Schlüssel im Header Authorization: Bearer. API-Schlüssel in URL-Abfrageparametern werden abgewiesen, da URLs von Proxys und in Zugriffsprotokollen gespeichert werden können.

Änderung bei der Authentifizierung

Früher wurde der API-Schlüssel als URL-Parameter api_key akzeptiert. Anfragen mit ?api_key=YOUR_API_KEY funktionieren nicht mehr. Verwende stattdessen den HTTP-Header Authorization:

Authorization: Bearer YOUR_API_KEY

Die Beispiele verwenden YOUR_API_KEY, die Gruppen-ID 123 und https://www.loomio.com/. Ersetze sie durch deinen API-Schlüssel, deine Gruppen-ID und die URL deiner Loomio-Installation.

Größe der Antworten und verknüpfte Datensätze

Antworten der Benutzer-API haben ein zusammengesetztes Format: Neben den angeforderten Datensätzen enthalten sie verknüpfte Datensätze wie Topics, Gruppen, Benutzer, Abstimmungen und Reaktionen. So kann ein Client seinen lokalen Datenspeicher mit einer einzigen Anfrage füllen. Die Antwort kann dadurch aber mehr Daten enthalten, als eine einfache Integration benötigt.

Mit compact=1 lässt du umfangreiche verknüpfte Topics, Gruppen, übergeordnete Gruppen, Mitgliedschaften, Reaktionen, Schlagwörter und Übersetzungen weg. Die angeforderten Datensätze und die zum Verständnis ihrer Inhalte benötigten verknüpften Datensätze bleiben erhalten.

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads/123/items?compact=1'

Mit exclude_types kannst du gezielt Datensatztypen ausschließen. Gib dazu die Typen im Singular durch Leerzeichen getrennt an. Beispielsweise lässt exclude_types=group reaction verknüpfte Gruppen und Reaktionen weg. Häufige Werte sind topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome und topic_item. Der Ausschluss betrifft verknüpfte Datensätze, nicht die vom Endpunkt angeforderte Hauptressource.

Antworten auf Sammlungsanfragen enthalten meta.total, wenn eine genaue Anzahl definiert ist. Die Anzahl wird vor der Anwendung von limit und offset berechnet. Endpunkte wie die Suche, die ihre Ergebnismenge bewusst begrenzen, lassen meta.total weg, statt null zurückzugeben.

Übersicht der Endpunkte

Gruppen

Gruppen auflisten

Ruft die Gruppen ab, in denen der API-Schlüssel-Benutzer eine aktive Mitgliedschaft hat.

GET /api/b2/groups

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups

Die Antwort enthält alle passenden Datensätze in einem groups-Array ohne Paginierung. Dazu gehören übergeordnete Gruppen und Untergruppen, auch wenn deren Abonnement derzeit nicht aktiv ist. Prüfe das Feld enabled, wenn eine Integration nur für aktivierte Gruppen arbeiten soll.

Wichtige Gruppenfelder sind:

Die Antwort kann weitere Gruppeneinstellungen, verknüpfte Datensätze übergeordneter Gruppen und die Mitgliedschaften des API-Benutzers enthalten. Clients sollten Felder ignorieren, die sie nicht verwenden.

Eine Gruppe abrufen

Ruft eine Gruppe ab, die für den API-Schlüssel-Benutzer sichtbar ist.

GET /api/b2/groups/:id_or_key_or_handle

Als Kennung kannst du die numerische ID, den Schlüssel oder die lesbare Kennung der Gruppe verwenden.

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups/123
curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups/example-group

Die Antwort enthält die Gruppe im groups-Array und verwendet dieselben Felder wie der Endpunkt zum Auflisten. Wenn der API-Schlüssel-Benutzer keinen Zugriff auf die Gruppe hat, wird ein Berechtigungsfehler zurückgegeben.

Webhooks

Die Benutzer-API arbeitet mit Anfragen: Eine Integration ruft Loomio auf, wenn sie Daten lesen oder ändern möchte. Ein Gruppen-Webhook übermittelt Ereignisse in die andere Richtung. Loomio sendet ausgewählte Gruppenereignisse an deinen Endpunkt, sobald sie eintreten. Die Integration muss die REST-API daher nicht regelmäßig auf Änderungen abfragen.

Webhooks werden für jede Gruppe einzeln eingerichtet. Dafür sind Administratorrechte in der Gruppe erforderlich. Du kannst sie über die Loomio-Oberfläche verwalten:

1. Öffne die Gruppe.
2. Öffne das Gruppenmenü und wähle Chat-Integrationen.
3. Füge die Integration hinzu, deren Nutzdatenformat dein Endpunkt unterstützt. Verwende für einen allgemeinen Endpunkt das Format Mattermost/Markdown.
4. Gib einen Namen und die Ziel-URL ein.
5. Wähle die Ereignisse aus, die Loomio automatisch senden soll.
6. Speichere die Integration und sende mit Testverbindung eine Testnachricht.

Verwende ein HTTPS-Ziel mit einer nicht erratbaren URL. Loomio verlangt, dass das Ziel zu einer öffentlichen Adresse aufgelöst wird, und blockiert Anfragen an lokale oder private Netzwerkadressen.

Agenten und andere Integrationen können Webhooks auch über die unten beschriebenen Chatbot-Endpunkte mit Bearer-Authentifizierung verwalten. Die Ressource heißt aus Kompatibilitätsgründen mit Loomios Chat-Integrationen chatbots, steht aber auch für allgemeine ausgehende Webhooks.

Webhooks auflisten

Ruft die für eine Gruppe eingerichteten Chat-Integrationen ab. Der API-Schlüssel-Benutzer muss Administrator dieser Gruppe sein. Die Antwort enthält Ziel-URLs und darf daher gewöhnlichen Gruppenmitgliedern nicht zugänglich gemacht werden.

GET /api/b2/chatbots?group_id=123

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/chatbots?group_id=123'

Die Antwort enthält ein chatbots-Array mit diesen Feldern:

Webhook erstellen

POST /api/b2/chatbots

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "group_id": 123,
    "name": "Planning system",
    "kind": "webhook",
    "webhook_kind": "markdown",
    "server": "https://hooks.example.org/loomio/unguessable-token",
    "event_kinds": ["new_discussion", "new_comment", "poll_created", "outcome_created"],
    "notification_only": false
  }' \
  https://www.loomio.com/api/b2/chatbots

Der Benutzer des API-Schlüssels muss Administrator der Gruppe group_id sein. Vor dem Speichern wird geprüft, ob die Ziel-URL öffentlich erreichbar ist.

Webhook aktualisieren

PATCH /api/b2/chatbots/:id

Sende die Felder, die geändert werden sollen. Durch Ändern von group_id kannst du den Webhook nicht einer anderen Gruppe zuordnen.

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Planning events","event_kinds":["new_discussion","outcome_created"]}' \
  https://www.loomio.com/api/b2/chatbots/456

Webhook-Ziel testen

Sende vor oder nach dem Speichern der Konfiguration eine Markdown-kompatible Testnachricht an das Ziel.

POST /api/b2/chatbots/check

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":123,"server":"https://hooks.example.org/loomio/unguessable-token"}' \
  https://www.loomio.com/api/b2/chatbots/check

Webhook löschen

DELETE /api/b2/chatbots/:id

curl -X DELETE -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/chatbots/456

Wenn du die Konfiguration löschst, werden keine weiteren Ereignisse zugestellt. Inhalte der Loomio-Gruppe bleiben erhalten.

Ereignistypen

Ein Webhook kann diese Ereignistypen abonnieren:

Der Webhook gehört zu einer Gruppe und empfängt deren abonnierte Ereignisse. Personen können die Integration beim Teilen oder Senden bestimmter Benachrichtigungen auch ausdrücklich auswählen, selbst wenn das entsprechende automatische Ereignis nicht ausgewählt ist.

HTTP-Zustellung

Loomio sendet asynchron einen HTTP-POST an die konfigurierte URL mit diesem Header:

Content-Type: application/json; charset=utf-8

Die Zeitüberschreitung für die Anfrage beträgt fünf Sekunden. Eine 2xx-Antwort, einschließlich 204 No Content, gilt als erfolgreich. Webhook-Empfänger sollten zügig antworten, längere Aufgaben asynchron verarbeiten und doppelte oder in anderer Reihenfolge eintreffende Zustellungen berücksichtigen.

Loomio fügt derzeit weder eine Webhook-Signatur noch einen Header mit einem gemeinsamen Geheimnis, eine Ereignis-ID oder eine Zustellungs-ID hinzu. Behandle die vollständige Ziel-URL wie einen Zugangsschlüssel und veröffentliche sie nicht. Wenn der empfangende Dienst es unterstützt, füge der URL ein nicht erratbares Token hinzu. Wenn du ein stabiles maschinenlesbares Ereignisschema oder signierte Zustellungen benötigst, nutze den Webhook als Änderungsbenachrichtigung und rufe die aktuellen Datensätze über die authentifizierte Benutzer-API ab.

Nutzdatenformate

Webhook-Nutzdaten sind für Chat-Dienste aufbereitete Nachrichten. Sie enthalten keine vollständigen serialisierten Loomio-Datensätze. Links in der Nachricht verweisen auf die betroffenen Loomio-Inhalte. Wenn eine Integration den aktuellen Stand als strukturierte Daten benötigt, kann sie ihn über die Benutzer-API abrufen.

Das allgemeine Markdown-Format sendet beispielsweise einen Inhalt in dieser Form:

{
  "text": "Ada started a discussion: [Quarterly planning](https://example.loomio.org/d/example)",
  "icon_url": "https://example.loomio.org/path/to/group-logo.png",
  "username": "Loomio"
}

Der genaue Nachrichtentext hängt vom Ereignis, der Spracheinstellung der Gruppe, der Einstellung für reine Benachrichtigungen und der Loomio-Version ab. Empfänger sollten sich auf die dokumentierten Felder der obersten Ebene des gewählten Formats stützen, statt den Wortlaut der Sätze auszuwerten.

Suche

Suche nach Diskussionen, Kommentaren, Abstimmungen, Stimmen und Fazits, die für den Benutzer des API-Schlüssels sichtbar sind. Die Ergebnisse enthalten auch öffentliche Inhalte aus Gruppen, denen der Benutzer nicht angehört. Für private Inhalte gelten die üblichen Sichtbarkeitsregeln für Themen.

GET /api/b2/search

Parameter

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/search?query=quarterly+planning&type=Discussion'

Die Antwort enthält ein search_results-Array. Jedes Ergebnis kennzeichnet den gefundenen Datensatz und seinen sichtbaren Kontext. Dazu gehören die Felder searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at und tags. Felder, die für ein Ergebnis nicht gelten, haben den Wert null.

Bericht zur Beteiligung

Gibt dieselben zusammengefassten Beteiligungsdaten zurück, die Loomio im Bericht zur Beteiligung verwendet.

GET /api/b2/reports

Parameter

Eine Person gilt als delegiert, wenn sie in mindestens einer ausgewählten Gruppe eine aktive Mitgliedschaft als Delegierte hat. Ihre Zahlen werden über alle ausgewählten Gruppen zusammengefasst. Zeilen für Delegierte werden auch dann zurückgegeben, wenn alle Aktivitätszahlen null sind. Die Zahlen umfassen Threads, Kommentare, Abstimmungen, Stimmen, Fazits und Reaktionen. Sie sind keine Quoten für die Teilnahme an Abstimmungen. Benutzerzeilen enthalten außerdem die Zahlen der für identifizierte Personen ausgegebenen, abgegebenen und nicht abgegebenen Stimmzettel. Anonyme Abstimmungen sind von allen personenbezogenen Stimmzahlen ausgenommen. all_votes_cast ist nur dann wahr, wenn mindestens ein Stimmzettel ausgegeben und jeder ausgegebene Stimmzettel abgegeben wurde.

Die API wendet dieselben Regeln für die Sichtbarkeit von Gruppen an wie der Bericht in Loomio. Ein Schlüssel der Benutzer-API kann keine Berichtsdaten aus Gruppen offenlegen, auf die sein Benutzer keinen Zugriff hat.

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09'

Das users-Array enthält vollständige Zeilen mit Aktivitätsdaten:

{
  "users": [
    {
      "id": 456,
      "name": "Ada Lovelace",
      "country": "NZ",
      "delegate": true,
      "threads": 2,
      "comments": 8,
      "polls": 1,
      "votes": 5,
      "votes_cast": 5,
      "votes_issued": 6,
      "votes_missed": 1,
      "all_votes_cast": false,
      "outcomes": 1,
      "reactions": 4
    }
  ]
}

Diskussion erstellen

Erstelle eine Diskussion mit dem Benutzerkonto, zu dem der API-Schlüssel gehört.

POST /api/b2/discussions

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "title":"example thread", "recipient_emails":["person@example.com"]}' https://www.loomio.com/api/b2/discussions

Diskussion abrufen

Rufe eine Diskussion über ihre numerische ID oder ihren Schlüssel als Zeichenfolge ab.

GET /api/b2/discussions/:id

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/discussions/abc123

Diskussionen auflisten

Liste die Diskussionen einer Gruppe auf, die für den Benutzer mit dem API-Schlüssel sichtbar sind. In einer öffentlich sichtbaren Gruppe können auch Personen ohne Mitgliedschaft die öffentlichen Diskussionen auflisten. Private Diskussionen bleiben auf Personen beschränkt, die sie in Loomio lesen dürfen.

GET /api/b2/discussions

Parameter

Aus Kompatibilitätsgründen werden per und from weiterhin als alternative Namen für limit und offset akzeptiert.

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/discussions?group_id=123'

Threads auflisten

Liste die für den Benutzer mit dem API-Schlüssel sichtbaren Diskussions- und Abstimmungs-Threads auf, sortiert nach der letzten Aktivität. Die ID eines Threads ist seine topic_id.

GET /api/b2/threads

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads?limit=50&offset=0'

Thread lesen

Lies einen Thread, seine chronologisch geordneten Ereignisse oder sein vollständiges sichtbares Markdown-Dokument.

GET /api/b2/threads/:topic_id

GET /api/b2/threads/:topic_id/items

GET /api/b2/threads/:topic_id/markdown

Beispiel

GET https://www.loomio.com/api/b2/threads/<topic_id>
GET https://www.loomio.com/api/b2/threads/<topic_id>/items
GET https://www.loomio.com/api/b2/threads/<topic_id>/markdown

Der Endpunkt items gibt die Ereignisse in ihrer Reihenfolge zurück, einschließlich sichtbarer Kommentare, Abstimmungen, Stimmen und Fazits. Der Endpunkt markdown gibt den vollständigen sichtbaren Thread als ein Markdown-Dokument zurück. Begründungen für Stimmen sind nur enthalten, wenn sie für den Benutzer mit dem API-Schlüssel sichtbar sind.

Für alle Thread-Endpunkte gelten dieselben Berechtigungen wie in der Loomio-Oberfläche. Der API-Schlüssel gewährt keinen Zugriff auf einen Thread, den der Benutzer normalerweise nicht öffnen kann.

Diskussion bearbeiten

Bearbeite eine Diskussion mit dem Benutzerkonto, zu dem der API-Schlüssel gehört. Es gelten dieselben Berechtigungen wie in Loomio: Der Benutzer muss diese Diskussion bearbeiten dürfen.

PATCH /api/b2/discussions/:id

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"title":"updated thread title", "description":"updated context", "description_format":"md"}' https://www.loomio.com/api/b2/discussions/123

Diskussion vorläufig löschen

Lösche eine Diskussion mit dem Benutzerkonto, zu dem der API-Schlüssel gehört, vorläufig. Die Diskussion wird verworfen, ihr Datensatz bleibt jedoch erhalten.

DELETE /api/b2/discussions/:id

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/discussions/123

Kommentar erstellen

Erstelle mit dem Benutzerkonto, zu dem der API-Schlüssel gehört, einen Kommentar in einer Diskussion.

POST /api/b2/comments

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"discussion_id": 123, "body":"example comment", "body_format":"md"}' https://www.loomio.com/api/b2/comments

Kommentar bearbeiten

Bearbeite einen Kommentar mit dem Benutzerkonto, zu dem der API-Schlüssel gehört. Es gelten dieselben Berechtigungen wie in Loomio: Der Benutzer muss diesen Kommentar bearbeiten dürfen.

PATCH /api/b2/comments/:id

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"body":"updated comment", "body_format":"md"}' https://www.loomio.com/api/b2/comments/123

Kommentar vorläufig löschen

Lösche einen Kommentar mit dem Benutzerkonto, zu dem der API-Schlüssel gehört, vorläufig. Der Kommentar wird verworfen und sein Text ausgeblendet, sein Datensatz bleibt jedoch erhalten.

DELETE /api/b2/comments/:id

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/comments/123

Umfrage erstellen

Erstelle eine Umfrage mit dem Benutzerkonto, zu dem der API-Schlüssel gehört.

POST /api/b2/polls

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "title":"example poll", "poll_type": "proposal", "options": ["agree", "disagree"], "closing_at": "2026-09-01T12:00:00Z", "recipient_emails":["person@example.com"]}' https://www.loomio.com/api/b2/polls

Umfrage abrufen

Rufe eine Umfrage über ihre numerische ID oder ihren Schlüssel als Zeichenfolge ab.

GET /api/b2/polls/:id

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/polls/abc123

Umfragen auflisten

Liste die Umfragen einer Gruppe auf, die für die Person mit dem API-Schlüssel sichtbar sind. In einer öffentlich sichtbaren Gruppe können auch Personen ohne Mitgliedschaft öffentliche Umfragen auflisten. Private Umfragen sind nur für Personen sichtbar, die sie in Loomio lesen dürfen. Die Antwort enthält das aktuelle Fazit jeder sichtbaren Umfrage. Mit status=closed kannst du daher Vorschläge mit einem Fazit auflisten.

GET /api/b2/polls

Parameter

Aus Kompatibilitätsgründen werden per und from weiterhin als alternative Namen für limit und offset akzeptiert.

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/polls?group_id=123'

Umfrage bearbeiten

Bearbeite eine Umfrage mit dem Benutzerkonto, zu dem der API-Schlüssel gehört. Es gelten dieselben Berechtigungen wie in Loomio: Die Person muss diese Umfrage bearbeiten dürfen.

PATCH /api/b2/polls/:id

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"title":"updated poll title", "details":"updated details", "details_format":"md"}' https://www.loomio.com/api/b2/polls/123

Umfrage vorläufig löschen

Lösche eine Umfrage vorläufig mit dem Benutzerkonto, zu dem der API-Schlüssel gehört. Die Umfrage wird verworfen, ihr Datensatz bleibt jedoch erhalten.

DELETE /api/b2/polls/:id

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/polls/123

Mitgliedschaften auflisten

Liste die Mitgliedschaften auf, die für die Person mit dem API-Schlüssel sichtbar sind. Gruppenmitglieder können Namen, IDs, Titel und Rollen der Mitglieder lesen. E-Mail-Adressen werden nur für das eigene Konto oder für Gruppenadministratoren angezeigt.

GET /api/b2/memberships

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/memberships?group_id=123'

Mitgliedschaften verwalten

Sende eine Liste von E-Mail-Adressen. Neue Adressen auf der Liste erhalten eine Einladung zur Gruppe. Anders als beim Auflisten von Mitgliedschaften benötigst du für diese Aktion Gruppenadministratorrechte.

POST /api/b2/memberships

Parameter

Beispiel

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "emails":["person@example.com"]}' https://www.loomio.com/api/b2/memberships

Wenn du remove_absent=1 angibst, werden alle Gruppenmitglieder entfernt, die nicht auf der Liste stehen. Achte darauf, dass du damit alle Mitglieder deiner Gruppe entfernen könntest.

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "emails":["person@example.com"], "remove_absent": 1}' https://www.loomio.com/api/b2/memberships

Die Antwort ist ein Objekt mit {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.