Dokumentation der Loomio-Benutzer-API

/api/user0 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.

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.

Anfrageinhalte senden

Sende JSON mit Content-Type: application/json. Die cURL-Beispiele verwenden --json, wodurch dieser Header automatisch gesetzt wird. Die Endpunkte zum Erstellen und Bearbeiten von Diskussionen, Kommentaren und Abstimmungen akzeptieren entweder ein flaches Objekt oder ein unter dem Ressourcennamen verschachteltes Objekt, etwa {"poll": {...}}.

Sende Arrays als JSON-Arrays, etwa "options": ["foo", "bar"]. Wenn du stattdessen Formularkodierung verwendest, benötigen Arrays Feldnamen mit eckigen Klammern, etwa options[]=foo&options[]=bar; bei der Wiederholung options=foo&options=bar bleibt nur der letzte Wert erhalten.

Prüfe nach jeder Anfrage den HTTP-Status und den Antwortinhalt. Bei einem Validierungsfehler wird 422 mit einem errors-Objekt zurückgegeben; nach dem erfolgreichen Erstellen einer Abstimmung enthält die Antwort die Abstimmung in polls und ihre Optionen in poll_options.

Übersicht der Endpunkte

Seiteneinteilung

Diskussionen, Gruppen, Mitgliedschaften, Abstimmungen, Threads, Thread-Einträge und Webhooks akzeptieren limit (Standardwert 50) und offset (Standardwert 0). Bei Gruppen, Thread-Einträgen und Webhooks ist limit auf 500 begrenzt.

Erhöhe offset um die Anzahl der zurückgegebenen primären Datensätze, um die nächste Seite abzurufen. meta.total ist die Gesamtanzahl der passenden Datensätze; zugehörige Datensätze zählen nicht zur Seitengröße.

Beteiligungsberichte geben die angeforderten Daten vollständig zurück, die Suche liefert bis zu 20 Ergebnisse. Beide unterstützen keine Seiteneinteilung.

Diskussionen, Abstimmungen und Mitgliedschaften akzeptieren außerdem die älteren Aliasse per für limit und from für offset. Verwende für neue Integrationen limit und offset.

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.

Übergib 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 'https://www.loomio.com/api/user0/threads/123/items?compact=1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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.

Kommentare

Kommentar erstellen

Erstelle einen Kommentar in einer Diskussion im Namen des Kontos, zu dem der API-Schlüssel gehört.

POST /api/user0/comments

Parameter

Beispiel

curl https://www.loomio.com/api/user0/comments \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "discussion_id": 123,
    "body": "example comment",
    "body_format": "md"
  }'

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/user0/comments/:id

Parameter

Beispiel

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

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/user0/comments/:id

Beispiel

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

Diskussionen

Diskussion erstellen

Erstelle eine Diskussion im Namen der Person mit dem API-Schlüssel.

POST /api/user0/discussions

Parameter

Beispiel

curl https://www.loomio.com/api/user0/discussions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example thread",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Diskussion abrufen

Rufe eine Diskussion über ihre ID (eine Ganzzahl) oder ihren Schlüssel (eine Zeichenfolge) ab.

GET /api/user0/discussions/:id

Beispiel

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

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/user0/discussions

Parameter

Abwärtskompatibilität: per und from werden als Aliasse für limit und offset akzeptiert und funktionieren weiterhin.

Beispiel

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

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/user0/discussions/:id

Parameter

Beispiel

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

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/user0/discussions/:id

Beispiel

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

Gruppen

Gruppen auflisten

Gibt die Gruppen zurück, in denen das Konto, dessen API-Schlüssel verwendet wird, eine aktive Mitgliedschaft hat.

GET /api/user0/groups

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

Die Antwort enthält eine Seite mit groups, aufsteigend nach Gruppen-ID sortiert, sowie die Gesamtzahl der passenden Gruppen in meta.total. 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:

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/user0/groups/:id_or_key_or_handle

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

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

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

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.

Mitgliedschaften

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/user0/memberships

Parameter

Abwärtskompatibilität: per und from werden als Aliase für limit und offset akzeptiert und funktionieren weiterhin.

Die Antwort enthält eine Seite mit memberships und zugehörigen users. meta.total ist die Gesamtzahl der sichtbaren Mitgliedschaften in der Gruppe vor der Seiteneinteilung.

Beispiel

curl 'https://www.loomio.com/api/user0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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/user0/memberships

Parameter

Beispiel

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ]
  }'

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 https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ],
    "remove_absent": 1
  }'

Dies gibt ein Objekt mit {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]} zurück.

Beteiligungsbericht

Rufe dieselben zusammengefassten Beteiligungsdaten ab, die im Beteiligungsbericht von Loomio verwendet werden.

GET /api/user0/reports

Parameter

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 'https://www.loomio.com/api/user0/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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
    }
  ]
}

Abstimmungen

Abstimmung erstellen

Erstelle eine Abstimmung im Namen des Kontos, zu dem der API-Schlüssel gehört.

POST /api/user0/polls

Parameter

Beispiel

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

Einen Abstimmungsentwurf mit vielen Optionen erstellen

Sende alle Optionsnamen im options-Array. Wenn du closing_at weglässt, wird eine Abstimmung in Bearbeitung erstellt, bei der die Stimmabgabe deaktiviert ist; die Abstimmung bleibt für Personen sichtbar, die ihren Thread lesen können. Füge einen zukünftigen Wert für closing_at hinzu, wenn du die Stimmabgabe öffnen möchtest.

Füge alle deine Optionsnamen zum Array hinzu:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Meeting venue",
    "poll_type": "poll",
    "options": [
      "Town hall",
      "Library",
      "Community centre"
    ]
  }'

Abstimmung mit detaillierten Optionen erstellen

Verwende options für eine Liste von Namen oder poll_options_attributes, wenn jede Option eine Bedeutung, eine Aufforderung zur Begründung oder ein Symbol benötigt. Wähle pro Anfrage ein Format. Beide Formate funktionieren in einem flachen JSON-Anfragetext oder innerhalb eines poll-Objekts.

Jedes Objekt in poll_options_attributes akzeptiert diese Felder:

Erstelle einen Vorschlag mit eigenen Optionsbeschriftungen und Aufforderungen:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Should we adopt this proposal?",
    "poll_type": "proposal",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Support",
        "meaning": "I support adopting this proposal",
        "prompt": "What do you support about it?",
        "icon": "agree",
        "priority": 0
      },
      {
        "name": "Oppose",
        "meaning": "I would prefer another approach",
        "prompt": "What would you change?",
        "icon": "disagree",
        "priority": 1
      }
    ]
  }'

Verwende für eine reguläre Abstimmung dasselbe Format für detaillierte Optionen und setze eine gemeinsame Aufforderung zur Begründung mit reason_prompt für die Abstimmung:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Choose a venue",
    "poll_type": "poll",
    "reason_prompt": "Why do you prefer this venue?",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Town hall",
        "meaning": "Central, accessible venue",
        "priority": 0
      },
      {
        "name": "Library",
        "meaning": "Smaller room with no hire fee",
        "priority": 1
      }
    ]
  }'

Diese Beispiele lassen closing_at weg. Die Stimmabgabe bleibt daher deaktiviert, bis ein zukünftiges Enddatum festgelegt wird.

Abstimmung abrufen

Rufe eine Abstimmung anhand ihrer ID (einer Ganzzahl) oder ihres Schlüssels (einer Zeichenkette) ab.

GET /api/user0/polls/:id

Beispiel

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

Abstimmungen auflisten

Liste die Abstimmungen einer Gruppe auf, die für die Person sichtbar sind, deren API-Schlüssel verwendet wird, einschließlich eigenständiger Abstimmungen und Abstimmungen innerhalb von Diskussionen. 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 beendete Abstimmungen auflisten und deren Fazits lesen, sofern diese bereits verfasst wurden.

Um den Entscheidungsstatus neben Diskussionen anzuzeigen, rufe Diskussionen und Abstimmungen derselben Gruppe ab. Verwende dabei status=all für die Abstimmungen und ordne sie anhand ihrer topic_id-Werte zu. Rufe mit limit und offset jede Seite ab. Eine Diskussion kann mehrere Abstimmungen enthalten. Wähle daher aus, welche Abstimmung den angezeigten Status bestimmt, zum Beispiel die zuletzt erstellte Abstimmung. Ein Wert ungleich null für closed_at kennzeichnet eine beendete Abstimmung; ein null-Wert für closing_at kennzeichnet einen Entwurf. Wenn eine Abstimmung ein Fazit hat, verweist ihre current_outcome_id auf einen Datensatz im outcomes-Array der Antwort. Ordne diesen Datensatz anhand seiner poll_id der id der Abstimmung zu.

Für eine einzelne Diskussion kannst du auch mit GET /api/user0/threads/:topic_id/items die Elemente ihres Threads lesen. Dadurch werden die Abstimmungen und Fazits des Threads zusammen mit seinen übrigen Elementen zurückgegeben. Rufe jede Seite ab, um den vollständigen Thread zu erhalten.

GET /api/user0/polls

Parameter

Abwärtskompatibilität: per und from werden als Aliasse für limit und offset akzeptiert und funktionieren weiterhin.

Beispiel

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

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/user0/polls/:id

Parameter

Beispiel

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

Detaillierte Optionen bearbeiten

Entnimm die Options-IDs dem poll_options-Array in der Antwort auf eine Anfrage zum Erstellen oder Abrufen einer Abstimmung. Sende nur die zu ändernden Felder zusammen mit der id der jeweiligen bestehenden Option:

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "poll_options_attributes": [
      {
        "id": 456,
        "meaning": "Updated explanation",
        "prompt": "What would improve this proposal?"
      },
      {
        "name": "Abstain",
        "meaning": "I leave the decision to others",
        "icon": "abstain",
        "priority": 2
      }
    ]
  }'

Options-IDs müssen zur bearbeiteten Abstimmung gehören. Zum Bearbeiten ist die Berechtigung zum Bearbeiten der Abstimmung erforderlich. Beendete Abstimmungen können nicht bearbeitet werden. Bei anonymen Abstimmungen kann außerdem die Konfiguration der Optionen nach der ersten Stimmabgabe nicht mehr geändert werden.

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/user0/polls/:id

Beispiel

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

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/user0/search

Parameter

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

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.

Threads

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/user0/threads

Parameter

Beispiel

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

Thread lesen

Lies einen Thread, seinen geordneten Ereignisstrom oder sein vollständiges sichtbares Markdown-Dokument.

GET /api/user0/threads/:topic_id

GET /api/user0/threads/:topic_id/items

GET /api/user0/threads/:topic_id/markdown

Der Endpunkt items akzeptiert diese Parameter zur Seiteneinteilung:

Beispiel

GET https://www.loomio.com/api/user0/threads/<topic_id>
GET https://www.loomio.com/api/user0/threads/<topic_id>/items?limit=50&offset=0
GET https://www.loomio.com/api/user0/threads/<topic_id>/markdown

Der Endpunkt items gibt eine Seite des Ereignisstroms in aufsteigender Reihenfolge zurück, einschließlich sichtbarer Kommentare, Abstimmungen, Stimmen und Fazits. meta.total ist die Gesamtzahl der Einträge im Thread. Rufe die folgenden Seiten ab, um den gesamten Ereignisstrom zu lesen. 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.

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/user0/chatbots?group_id=123

curl 'https://www.loomio.com/api/user0/chatbots?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Die Antwort enthält eine Seite von chatbots, sortiert nach aufsteigender Integrations-ID, mit der Gesamtzahl für die Gruppe in meta.total. Jede Integration hat diese Felder:

Einen Webhook erstellen

POST /api/user0/chatbots

curl https://www.loomio.com/api/user0/chatbots \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "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
  }'

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/user0/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 https://www.loomio.com/api/user0/chatbots/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "name": "Planning events",
    "event_kinds": [
      "new_discussion",
      "outcome_created"
    ]
  }'

Ein Webhook-Ziel testen

Sende eine Markdown-kompatible Testnachricht an ein Ziel, bevor oder nachdem du dessen Konfiguration speicherst.

POST /api/user0/chatbots/check

curl https://www.loomio.com/api/user0/chatbots/check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "server": "https://hooks.example.org/loomio/unguessable-token"
  }'

Webhook löschen

DELETE /api/user0/chatbots/:id

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

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:

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.

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.