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.

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:

  1. Öffne die Gruppe.
  2. Öffne das Gruppenmenü und wähle Chat-Integrationen.
  3. Füge die Integration hinzu, die zum Nutzdatenformat passt, das dein Endpunkt akzeptiert. Verwende für einen allgemein nutzbaren Endpunkt das Mattermost/Markdown-Format.
  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 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 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.

Diese Seite wurde maschinell übersetzt. Wenn ein Wort falsch oder unklar ist, schreib eine E-Mail an contact@loomio.org, und wir korrigieren es.