Dokumentation der Loomio-Benutzer-API
/api/b2 ist die benutzerorientierte API für Integrationen mit Loomio. Sie verwendet den API-Schlüssel eines Benutzerkontos, und jede Aktion wird im Namen dieses Kontos ausgeführt.
Gruppenaktionen verwenden die Mitgliedschaften und Gruppenberechtigungen des Kontos, dessen API-Schlüssel verwendet wird. Administrationsrechte für die Instanz erweitern den Zugriff eines API-Schlüssels auf Gruppen oder Inhalte nicht; nutze für die Verwaltung auf Instanzebene die Server-API.
Verwende den API-Schlüssel des Loomio-Benutzerkontos, das die Aktionen ausführen soll. Ein eigenes Bot-Konto ist sinnvoll, wenn eine Integration keine Einladungen zu Abstimmungen oder Benachrichtigungen erhalten soll.
Angemeldete Personen finden ihren API-Schlüssel und ihre Gruppen-IDs auf der Seite für den API-Zugriff.
Sende den API-Schlüssel in einem Authorization: Bearer-Header. API-Schlüssel in Abfrageparametern werden abgelehnt, da URLs von Proxys und in Zugriffsprotokollen aufgezeichnet werden können.
Änderung der Authentifizierung
Der API-Schlüssel wurde bisher 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 diese durch deinen API-Schlüssel, deine Gruppen-ID und die URL deiner Loomio-Installation.
Antwortgröße und zugehörige Datensätze
Antworten der Benutzer-API verwenden ein zusammengesetztes Format: Die primären Datensätze werden durch zugehörige Datensätze wie Topics, Gruppen, Benutzerkonten, Abstimmungen und Reaktionen ergänzt. So kann ein Client mit einer einzigen Anfrage einen lokalen Datenspeicher befüllen. Die Antwort kann jedoch mehr Daten enthalten, als eine einfache Integration benötigt.
Übergebe compact=1, um umfangreiche zugehörige Topics, Gruppen, Hauptgruppen, Mitgliedschaften, Reaktionen, Schlagwörter und Übersetzungen wegzulassen. Primäre Datensätze und die zugehörigen Datensätze, die zum Verständnis ihrer Inhalte benötigt werden, bleiben enthalten.
curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads/123/items?compact=1'
Für eine gezielte Steuerung übergib exclude_types mit durch Leerzeichen getrennten Datensatztypen im Singular. Beispielsweise lässt exclude_types=group reaction zugehörige Gruppen und Reaktionen weg. Übliche Werte sind topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome und topic_item. Ausschlüsse gelten für zugehörige Datensätze, nicht für die primäre Ressource, die über den Endpunkt angefordert wird.
Antworten mit Datensatzsammlungen enthalten meta.total, wenn eine genaue Gesamtanzahl definiert ist. Die Gesamtanzahl wird berechnet, bevor limit und offset angewendet werden. Endpunkte wie die Suche, die bewusst eine begrenzte Ergebnismenge zurückgeben, lassen meta.total weg, statt null zurückzugeben.
Übersicht der Endpunkte
| Methode | Endpunkt | Zweck |
|---|---|---|
GET |
/api/b2/groups |
Gruppen des Kontos auflisten, dessen API-Schlüssel verwendet wird |
GET |
/api/b2/groups/:id_or_key_or_handle |
Eine sichtbare Gruppe abrufen |
GET |
/api/b2/reports |
Einen Beteiligungsbericht erstellen |
GET |
/api/b2/search |
Sichtbare Diskussionen, Kommentare, Abstimmungen, Stimmen und Fazits durchsuchen |
POST |
/api/b2/discussions |
Eine Diskussion erstellen |
GET |
/api/b2/discussions/:id |
Eine Diskussion abrufen |
GET |
/api/b2/discussions |
Diskussionen in einer Gruppe auflisten |
PATCH |
/api/b2/discussions/:id |
Eine Diskussion bearbeiten |
DELETE |
/api/b2/discussions/:id |
Eine Diskussion als gelöscht markieren |
GET |
/api/b2/threads |
Sichtbare Diskussions-Threads und Threads eigenständiger Abstimmungen auflisten |
GET |
/api/b2/threads/:topic_id |
Einen Thread abrufen |
GET |
/api/b2/threads/:topic_id/items |
Die geordneten Einträge eines Threads abrufen |
GET |
/api/b2/threads/:topic_id/markdown |
Einen vollständigen Thread als Markdown abrufen |
POST |
/api/b2/comments |
Einen Kommentar oder eine Antwort erstellen |
PATCH |
/api/b2/comments/:id |
Einen Kommentar bearbeiten |
DELETE |
/api/b2/comments/:id |
Einen Kommentar als gelöscht markieren |
POST |
/api/b2/polls |
Eine Abstimmung erstellen |
GET |
/api/b2/polls/:id |
Eine Abstimmung abrufen |
GET |
/api/b2/polls |
Abstimmungen in einer Gruppe auflisten |
PATCH |
/api/b2/polls/:id |
Eine Abstimmung bearbeiten |
DELETE |
/api/b2/polls/:id |
Eine Abstimmung als gelöscht markieren |
GET |
/api/b2/memberships |
Mitgliedschaften einer Gruppe auflisten |
POST |
/api/b2/memberships |
Mitglieder hinzufügen und optional nicht aufgeführte Mitglieder entfernen |
GET |
/api/b2/chatbots |
Chat-Integrationen und Webhooks einer Gruppe auflisten |
POST |
/api/b2/chatbots |
Eine Chat-Integration oder einen Webhook erstellen |
PATCH |
/api/b2/chatbots/:id |
Eine Chat-Integration oder einen Webhook aktualisieren |
DELETE |
/api/b2/chatbots/:id |
Eine Chat-Integration oder einen Webhook löschen |
POST |
/api/b2/chatbots/check |
Einen Verbindungstest für einen Webhook senden |
Gruppen
Gruppen auflisten
Gibt die Gruppen zurück, in denen das Konto, dessen API-Schlüssel verwendet wird, 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 Seiteneinteilung. Sie umfasst Hauptgruppen und Untergruppen, einschließlich Gruppen, deren Abonnement derzeit nicht aktiv ist. Prüfe das Feld enabled, wenn eine Integration nur mit aktivierten Gruppen arbeiten soll.
Wichtige Gruppenfelder sind:
| Feld | Beschreibung |
|---|---|
id |
Numerische Gruppen-ID, die von anderen Endpunkten der Benutzer-API verwendet wird |
key |
Stabiler Kurzschlüssel, der in Loomio-URLs verwendet wird |
handle |
Lesbare Kennung der Gruppe |
name |
Gruppenname |
full_name |
Gruppenname einschließlich des Kontexts der Hauptgruppe |
parent_id |
Numerische ID der Hauptgruppe einer Untergruppe, andernfalls null |
enabled |
Ob die Gruppe und ihr Abonnement aktiv sind |
memberships_count |
Anzahl aktiver und ausstehender Mitgliedschaften |
accepted_memberships_count |
Anzahl angenommener Mitgliedschaften |
pending_memberships_count |
Anzahl ausstehender Einladungen |
admin_memberships_count |
Anzahl der Personen mit Administrationsrechten für die Gruppe |
delegates_count |
Anzahl der Delegierten |
discussions_count |
Anzahl der Diskussionen direkt in der Gruppe |
polls_count |
Anzahl der Abstimmungen direkt in der Gruppe |
subgroups_count |
Anzahl der Untergruppen |
Die Antwort kann zusätzliche Gruppeneinstellungen, zugehörige Datensätze der Hauptgruppen und die Mitgliedschaften des API-Kontos enthalten. Clients sollten Felder ignorieren, die sie nicht verwenden.
Eine Gruppe abrufen
Gibt eine Gruppe zurück, die für das Konto sichtbar ist, dessen API-Schlüssel verwendet wird.
GET /api/b2/groups/:id_or_key_or_handle
Als Bezeichner 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 von Gruppen. Eine Anfrage für eine Gruppe, auf die das Konto keinen Zugriff hat, gibt einen Berechtigungsfehler zurück.
Webhooks
Die Benutzer-API basiert auf Anfragen: Eine Integration ruft Loomio auf, wenn sie Daten lesen oder ändern möchte. Ein Gruppen-Webhook ermöglicht die Übertragung in die andere Richtung. Loomio sendet ausgewählte Gruppenereignisse an deinen Endpunkt, sobald sie eintreten. So muss eine Integration die REST-API nicht regelmäßig nach Änderungen abfragen.
Webhooks werden für jede Gruppe einzeln eingerichtet und erfordern Administrationsrechte für die Gruppe. Du kannst sie über die Loomio-Oberfläche verwalten:
- Öffne die Gruppe.
- Öffne das Gruppenmenü und wähle Chat-Integrationen.
- Füge die Integration hinzu, die zum Nutzdatenformat passt, das dein Endpunkt akzeptiert. Verwende für einen allgemein nutzbaren Endpunkt das Mattermost/Markdown-Format.
- Gib einen Namen und die Ziel-URL ein.
- Wähle die Ereignisse aus, die Loomio automatisch senden soll.
- 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 stattdessen ü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
Gibt die für eine Gruppe eingerichteten Chat-Integrationen zurück. Das Konto, dessen API-Schlüssel verwendet wird, muss Administrationsrechte für diese Gruppe haben. Die Antwort enthält Ziel-URLs und darf deshalb 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:
| Feld | Beschreibung |
|---|---|
id |
ID der Integration für Aktualisierungen und das Löschen |
group_id |
Gruppe, die die Ereignisse empfängt |
name |
Name zur Verwaltung der Integration |
kind |
webhook für einen ausgehenden Webhook oder matrix für eine Matrix-Integration |
webhook_kind |
Nutzdatenformat: markdown, slack, discord, microsoft oder webex |
server |
Ziel-URL |
event_kinds |
Automatisch gesendete Ereignisse |
notification_only |
Ob Nachrichten nur die Überschrift der Benachrichtigung enthalten |
Einen 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
Das Konto, dessen API-Schlüssel verwendet wird, muss Administrationsrechte für die Gruppe mit der ID group_id haben. Vor dem Speichern wird geprüft, ob das Ziel eine öffentliche URL ist.
Einen Webhook aktualisieren
PATCH /api/b2/chatbots/:id
Sende alle Felder, die geändert werden sollen. Durch eine Änderung von group_id kann der Webhook nicht in eine andere Gruppe übertragen werden.
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
Ein Webhook-Ziel testen
Sende eine Markdown-kompatible Testnachricht an ein Ziel, bevor oder nachdem du dessen Konfiguration speicherst.
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
Das Löschen der Konfiguration stoppt zukünftige Zustellungen. Dabei werden keine Inhalte der Loomio-Gruppe gelöscht.
Ereignistypen
Ein Webhook kann diese Ereignistypen abonnieren:
| Ereignis | Wann es gesendet wird |
|---|---|
new_discussion |
Eine Diskussion wird gestartet |
discussion_edited |
Eine Diskussion wird bearbeitet |
new_comment |
Ein Kommentar wird erstellt |
poll_created |
Eine Abstimmung wird gestartet |
poll_edited |
Eine Abstimmung wird bearbeitet |
poll_closing_soon |
Eine Abstimmung nähert sich ihrem Endzeitpunkt |
poll_expired |
Eine Abstimmung erreicht ihren Endzeitpunkt |
poll_closed_by_user |
Eine Person beendet eine Abstimmung manuell |
poll_reopened |
Eine Abstimmung wird wieder geöffnet |
outcome_created |
Ein Fazit wird veröffentlicht |
outcome_updated |
Ein Fazit wird aktualisiert |
outcome_review_due |
Die Überprüfung eines Fazits wird fällig |
stance_created |
Eine Stimme wird abgegeben |
stance_updated |
Eine Stimme wird geändert |
Der Webhook gehört zu einer Gruppe und empfängt die abonnierten Ereignisse aus dieser Gruppe. Personen können die Integration auch ausdrücklich beim Teilen oder beim Senden bestimmter Benachrichtigungen auswählen, selbst wenn das entsprechende automatische Ereignis nicht ausgewählt ist.
HTTP-Zustellung
Loomio sendet einen asynchronen HTTP POST mit diesem Header an die konfigurierte URL:
Content-Type: application/json; charset=utf-8
Das Zeitlimit für die Anfrage beträgt fünf Sekunden. Eine 2xx-Antwort, einschließlich 204 No Content, gilt als erfolgreich. Dienste, die Webhooks empfangen, sollten zügig antworten, längere Aufgaben asynchron verarbeiten und mit doppelten Zustellungen oder Zustellungen in abweichender Reihenfolge umgehen können.
Loomio fügt derzeit keine Webhook-Signatur, keinen Header mit einem gemeinsamen Geheimnis, keine Ereignis-ID und keine Zustellungs-ID hinzu. Behandle die vollständige Ziel-URL als Zugangsdaten, mache sie nicht öffentlich zugänglich und füge der URL ein nicht erratbares Token hinzu, wenn der empfangende Dienst dies unterstützt. Wenn du ein stabiles, maschinenlesbares Ereignisschema oder eine signierte Zustellung benötigst, verwende den Webhook als Änderungsbenachrichtigung und rufe die aktuellen Datensätze über die authentifizierte Benutzer-API ab.
Nutzdatenformate
Webhook-Nutzdaten sind für die Anzeige in Chatdiensten bestimmte Nachrichten. Sie sind keine vollständig serialisierten Loomio-Datensätze. Links in der Nachricht verweisen auf die betroffenen Loomio-Inhalte; eine Integration kann die Benutzer-API nutzen, wenn sie den aktuellen Stand in strukturierter Form benötigt.
| Integrationsformat | Wichtigste JSON-Felder |
|---|---|
| Mattermost/Markdown | text, icon_url, username |
| Slack | text |
| Discord | content, auf etwa 1.900 Zeichen begrenzt |
| Microsoft Teams | @type, @context, themeColor, text, sections |
| Webex | markdown |
Das allgemeine Markdown-Format sendet beispielsweise einen Nachrichteninhalt mit dieser Struktur:
{
"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 Sprache der Gruppe, der Einstellung für reine Benachrichtigungen und der Loomio-Version ab. Empfangende Dienste sollten sich auf die dokumentierten Felder der obersten Ebene des ausgewählten Formats verlassen, statt den Wortlaut der Sätze auszuwerten.
Suche
Suche nach Diskussionen, Kommentaren, Abstimmungen, Stimmen und Fazits, die für die Person mit dem API-Schlüssel sichtbar sind. Die Ergebnisse enthalten öffentliche Inhalte auch dann, wenn die Person kein Mitglied der jeweiligen Gruppe ist; für private Inhalte gelten weiterhin die üblichen Sichtbarkeitsregeln für Threads.
GET /api/b2/search
Parameter
| Name | Beschreibung |
|---|---|
query |
Suchtext. Exakte und unscharfe Treffer werden unterstützt |
group_id |
Beschränke die Ergebnisse auf eine sichtbare Gruppe |
org_id |
Beschränke die Ergebnisse auf eine sichtbare Hauptgruppe und ihre sichtbaren Untergruppen. Verwende 0 für direkte Diskussionen |
type |
Beschränke die Ergebnisse auf einen Typ: Discussion, Comment, Poll, Stance oder Outcome |
types |
Durch Kommas getrennte Liste der Ergebnistypen |
tag |
Beschränke die Ergebnisse auf Threads mit diesem Schlagwort |
author_id |
Beschränke die Ergebnisse auf Inhalte einer verfassenden Person. Ohne query wird deren jüngste sichtbare Aktivität zurückgegeben |
order |
Setze den Wert auf authored_at_desc, um passende Inhalte nach ihrem Erstellungszeitpunkt zu sortieren |
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 identifiziert den gefundenen Datensatz und seinen sichtbaren Kontext anhand von Feldern wie searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at und tags. Felder, die auf ein Ergebnis nicht zutreffen, haben den Wert null.
Beteiligungsbericht
Rufe dieselben zusammengefassten Beteiligungsdaten ab, die im Beteiligungsbericht von Loomio verwendet werden.
GET /api/b2/reports
Parameter
| Name | Beschreibung |
|---|---|
section |
Berichtsabschnitt: base, users oder countries. Verwende users für die Aktivität pro Person |
group_scope |
custom oder my. Der frühere Wert all wird wie my behandelt, da Schlüssel für die Benutzer-API niemals Zugriff auf die gesamte Instanz erhalten |
group_ids |
Durch Kommas getrennte Gruppen-IDs bei group_scope=custom. IDs von Gruppen, in denen die Person mit dem API-Schlüssel kein Mitglied ist, werden ignoriert |
start_month |
Erster einzubeziehender Monat im Format YYYY-MM; standardmäßig der Monat vor 12 Monaten |
end_month |
Letzter einzubeziehender Monat im Format YYYY-MM; standardmäßig der aktuelle Monat |
interval |
Intervall für den Abschnitt base: day, week, month oder year |
member_type |
Setze den Wert bei section=users auf delegate, um nur aktuelle Delegierte zurückzugeben |
Eine Person gilt als delegiert, wenn sie in mindestens einer ausgewählten Gruppe eine aktive Mitgliedschaft als delegierte Person hat. Ihre Anzahlen werden über alle ausgewählten Gruppen hinweg zusammengefasst. Zeilen für Delegierte werden auch dann zurückgegeben, wenn alle Aktivitätszahlen null sind. Die Anzahlen erfassen Threads, Kommentare, Abstimmungen, Stimmen, Fazits und Reaktionen; sie geben keine Beteiligungsquoten an Abstimmungen an. Die Zeilen für Personen enthalten außerdem die Anzahl der ausgegebenen, abgegebenen und nicht abgegebenen Stimmzettel bei nicht anonymen Abstimmungen. Anonyme Abstimmungen sind von allen personenbezogenen Zählungen zur Stimmabgabe ausgeschlossen. all_votes_cast ist nur dann wahr, wenn mindestens ein Stimmzettel ausgegeben und jeder ausgegebene Stimmzettel abgegeben wurde.
Die API wendet dieselben Sichtbarkeitsregeln für Gruppen an wie der Bericht in Loomio. Ein Schlüssel für die Benutzer-API kann keine Berichtsdaten aus Gruppen zugänglich machen, auf die die Person mit diesem Schlüssel 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 Aktivitätszeilen:
{
"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 im Namen der Person mit dem API-Schlüssel.
POST /api/b2/discussions
Parameter
| Name | Beschreibung |
|---|---|
group_id |
Gruppe, in der der Thread erstellt wird |
title |
Titel des Threads, erforderlich |
description |
Kontext des Threads, optional |
description_format |
Entweder md oder html, optional, standardmäßig md |
recipient_audience |
group oder null. Bei group wird die gesamte Gruppe über den neuen Thread benachrichtigt |
recipient_user_ids |
Array von Benutzer-IDs der Personen, die benachrichtigt oder zum Thread eingeladen werden sollen |
recipient_emails |
Array von E-Mail-Adressen der Personen, die zum Thread eingeladen werden sollen |
recipient_message |
Nachricht, die in die Einladung per E-Mail aufgenommen wird |
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 ID (eine Ganzzahl) oder ihren Schlüssel (eine 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 in einer Gruppe auf, die für die Person sichtbar sind, deren API-Schlüssel verwendet wird. Bei 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
| Name | Beschreibung |
|---|---|
group_id |
Ganzzahl, erforderlich. ID der Gruppe, deren Diskussionen aufgelistet werden sollen |
status |
Zeichenfolge, optional, Standardwert open. Werte: open, closed, all |
limit |
Ganzzahl, optional, Standardwert 50. Anzahl der Einträge pro Seite |
offset |
Ganzzahl, optional, Standardwert 0. Anzahl der Einträge, die bei der Seiteneinteilung übersprungen werden |
Abwärtskompatibilität: per und from werden als Aliasse für limit und offset akzeptiert und funktionieren weiterhin.
Beispiel
curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/discussions?group_id=123'
Threads auflisten
Liste die Diskussions- und Abstimmungs-Threads auf, die für die Person sichtbar sind, deren API-Schlüssel verwendet wird, sortiert nach der neuesten Aktivität. Die ID eines Threads ist seine topic_id.
GET /api/b2/threads
Parameter
| Name | Beschreibung |
|---|---|
limit |
Ganzzahl, optional, Standardwert 50. Anzahl der Einträge pro Seite |
offset |
Ganzzahl, optional, Standardwert 0. Anzahl der Einträge, die bei der Seiteneinteilung übersprungen werden |
Beispiel
curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads?limit=50&offset=0'
Thread lesen
Lies einen Thread, seinen geordneten Ereignisstrom 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 den geordneten Ereignisstrom 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 zu Stimmen werden nur aufgenommen, wenn sie für die Person sichtbar sind, deren API-Schlüssel verwendet wird.
Alle Thread-Endpunkte setzen dieselben Berechtigungen durch wie die Loomio-Oberfläche. Der API-Schlüssel gewährt keinen Zugriff auf einen Thread, den die Person normalerweise nicht öffnen darf.
Diskussion bearbeiten
Bearbeite eine Diskussion als die Person, deren API-Schlüssel verwendet wird. Es gelten dieselben Berechtigungen wie in Loomio: Die Person muss diese Diskussion bearbeiten dürfen.
PATCH /api/b2/discussions/:id
Parameter
| Name | Beschreibung |
|---|---|
title |
Aktualisierter Titel |
description |
Aktualisierter Kontext |
description_format |
Entweder md oder html, optional, Standardwert md |
recipient_audience |
group oder null. Bei group wird die gesamte Gruppe über die Bearbeitung benachrichtigt |
recipient_user_ids |
Array von Benutzer-IDs der Personen, die benachrichtigt oder zum Thread eingeladen werden sollen |
recipient_emails |
Array von E-Mail-Adressen der Personen, die zum Thread eingeladen werden sollen |
recipient_message |
Nachricht, die in die Einladung per E-Mail aufgenommen werden soll |
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 als gelöscht markieren
Markiere eine Diskussion im Namen des Kontos, zu dem der API-Schlüssel gehört, als gelöscht. Dadurch wird die Diskussion 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 einen Kommentar in einer Diskussion im Namen des Kontos, zu dem der API-Schlüssel gehört.
POST /api/b2/comments
Parameter
| Name | Beschreibung |
|---|---|
discussion_id |
Ganzzahl, erforderlich. ID der Diskussion, die du kommentieren möchtest |
body |
Kommentartext, erforderlich, sofern kein Anhang mitgesendet wird |
body_format |
Entweder md oder html, optional, Standardwert md |
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 im Namen des Kontos, zu dem der API-Schlüssel gehört. Es gelten dieselben Berechtigungen wie in Loomio: Das Konto muss diesen Kommentar bearbeiten dürfen.
PATCH /api/b2/comments/:id
Parameter
| Name | Beschreibung |
|---|---|
body |
Aktualisierter Kommentartext |
body_format |
Entweder md oder html, optional, Standardwert md |
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 als gelöscht markieren
Markiere einen Kommentar im Namen des Kontos, zu dem der API-Schlüssel gehört, als gelöscht. Dadurch wird der Kommentar 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
Abstimmung erstellen
Erstelle eine Abstimmung im Namen des Kontos, zu dem der API-Schlüssel gehört.
POST /api/b2/polls
Parameter
| Name | Beschreibung |
|---|---|
group_id |
Ganzzahl, optional, Standardwert null. ID der Gruppe für die Abstimmung. Wenn discussion_id übergeben wird, wird group_id ignoriert |
discussion_id |
Ganzzahl, optional, Standardwert null. ID des Diskussions-Threads, dem diese Abstimmung hinzugefügt werden soll |
title |
Zeichenfolge, erforderlich. Titel der Abstimmung |
poll_type |
Zeichenfolge, erforderlich. Werte: proposal, poll, count, score, ranked_choice, meeting, dot_vote |
details |
Zeichenfolge, optional. Text der Abstimmung |
details_format |
Zeichenfolge, optional, Standardwert md. Werte: md oder html |
options |
Array von Zeichenfolgen. Wenn poll_type den Wert proposal hat, sind die gültigen Werte agree (Zustimmung), disagree (Widerspruch), abstain (Enthaltung), block (Veto). Wenn poll_type den Wert meeting hat, gib Datums- oder Datumszeit-Zeichenfolgen im ISO-8601-Format an. Für alle anderen Abstimmungstypen ist jede Zeichenfolge gültig |
closing_at |
ISO-8601-Zeichenfolge oder null, Standardwert null. Beispiel: 2026-09-01T12:00:00Z. Bei null ist die Stimmabgabe deaktiviert und die Abstimmung gilt als in Bearbeitung |
specified_voters_only |
Boolescher Wert, optional, Standardwert false. Bei true können nur die angegebenen Personen abstimmen. Bei false werden alle Personen in der Gruppe zur Stimmabgabe eingeladen |
hide_results |
Zeichenfolge, optional, Standardwert off. Werte: off, until_vote, until_closed |
shuffle_options |
Boolescher Wert, Standardwert false. Zeigt den Abstimmenden die Optionen in zufälliger Reihenfolge an |
anonymous |
Boolescher Wert, optional, Standardwert false. Verbirgt die Identität der Abstimmenden |
recipient_audience |
group oder null, optional, Standardwert null. Bei group wird die gesamte Gruppe benachrichtigt |
notify_on_closing_soon |
Zeichenfolge, optional, Standardwert nobody. Werte: nobody, author, undecided_voters, voters |
recipient_user_ids |
Array von Benutzer-IDs der Personen, die benachrichtigt oder eingeladen werden sollen |
recipient_emails |
Array von E-Mail-Adressen der Personen, die zur Stimmabgabe eingeladen werden sollen |
recipient_message |
Nachricht, die in die Einladung per E-Mail aufgenommen werden soll |
notify_recipients |
Boolescher Wert, Standardwert false. Bei false werden Personen hinzugefügt, ohne Benachrichtigungen zu senden. Bei true erhalten alle mit dieser Anfrage eingeladenen Personen eine Benachrichtigung per E-Mail |
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
Abstimmung abrufen
Rufe eine Abstimmung anhand ihrer ID (einer Ganzzahl) oder ihres Schlüssels (einer Zeichenkette) ab.
GET /api/b2/polls/:id
Beispiel
curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/polls/abc123
Abstimmungen auflisten
Liste die Abstimmungen einer Gruppe auf, die für die Person sichtbar sind, deren API-Schlüssel verwendet wird. Bei einer öffentlich sichtbaren Gruppe können auch Personen ohne Mitgliedschaft deren öffentliche Abstimmungen auflisten; private Abstimmungen bleiben auf Personen beschränkt, die sie in Loomio lesen können. Die Antwort enthält das aktuelle Fazit jeder sichtbaren Abstimmung. Mit status=closed kannst du daher Vorschläge auflisten, über die bereits entschieden wurde.
GET /api/b2/polls
Parameter
| Name | Beschreibung |
|---|---|
group_id |
Ganzzahl, erforderlich. ID der Gruppe, deren Abstimmungen aufgelistet werden sollen |
status |
Zeichenkette, optional, Standardwert active. Werte: active, closed, all |
limit |
Ganzzahl, optional, Standardwert 50. Anzahl der Einträge pro Seite |
offset |
Ganzzahl, optional, Standardwert 0. Anzahl der Einträge, die bei der Seitennavigation übersprungen werden |
Abwärtskompatibilität: per und from werden als Aliasse für limit und offset akzeptiert und funktionieren weiterhin.
Beispiel
curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/polls?group_id=123'
Abstimmung bearbeiten
Bearbeite eine Abstimmung als die Person, deren API-Schlüssel verwendet wird. Es gelten dieselben Berechtigungen wie in Loomio: Diese Person muss die Abstimmung bearbeiten dürfen.
PATCH /api/b2/polls/:id
Parameter
| Name | Beschreibung |
|---|---|
title |
Aktualisierter Titel |
details |
Aktualisierte Details der Abstimmung |
details_format |
Entweder md oder html, optional, Standardwert md |
options |
Aktualisierte Optionsnamen. Änderungen an den Optionen können sich je nach Zustand der Abstimmung auf vorhandene Stimmen auswirken |
closing_at |
ISO-8601-Zeichenkette oder null |
recipient_audience |
group oder null. Bei group wird die gesamte Gruppe benachrichtigt |
recipient_user_ids |
Array von Benutzer-IDs der Personen, die benachrichtigt oder eingeladen werden sollen |
recipient_emails |
Array von E-Mail-Adressen der Personen, die zur Stimmabgabe eingeladen werden sollen |
recipient_message |
Nachricht, die in die Einladung per E-Mail aufgenommen werden soll |
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
Abstimmung als gelöscht markieren
Markiere eine Abstimmung als gelöscht, indem du den API-Schlüssel der handelnden Person verwendest. Dadurch wird die Abstimmung 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 sichtbar sind, deren API-Schlüssel verwendet wird. Gruppenmitglieder können Namen, IDs, Titel und Rollen der Mitglieder lesen. E-Mail-Adressen werden nur für das eigene Konto dieser Person ausgegeben oder wenn sie die Gruppe administriert.
GET /api/b2/memberships
Parameter
| Name | Beschreibung |
|---|---|
group_id |
Ganzzahl, erforderlich. ID der Gruppe, deren Mitgliedschaften aufgelistet werden sollen |
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. Alle neuen E-Mail-Adressen werden zur Gruppe eingeladen. Anders als beim Auflisten von Mitgliedschaften benötigst du für diesen Vorgang Berechtigungen zur Administration der Gruppe.
POST /api/b2/memberships
Parameter
| Name | Beschreibung |
|---|---|
group_id |
Ganzzahl, erforderlich. ID der Gruppe, deren Mitgliedschaften verwaltet werden sollen |
emails |
Array von Zeichenfolgen, erforderlich. E-Mail-Adressen der Personen, die zur Gruppe eingeladen werden sollen |
remove_absent |
Boolescher Wert. Wenn true, werden alle Personen aus der Gruppe entfernt, deren E-Mail-Adresse nicht in der Liste steht |
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 übergibst, werden alle Mitglieder aus der Gruppe entfernt, die nicht in der Liste enthalten sind. Sei vorsichtig: Du könntest alle Mitglieder deiner Gruppe entfernen.
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
Dies gibt ein Objekt mit {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]} zurück.