Documentatie van de Loomio Gebruikers-API

/api/b2 is de gebruikersgerichte API voor integraties met Loomio. Deze gebruikt de API-sleutel van een gebruikersaccount, en elke actie wordt uitgevoerd als die gebruiker.

Groepsbewerkingen gebruiken de lidmaatschappen en groepsrechten van de gebruiker van de API-sleutel. De status van instantiebeheerder geeft een API-sleutel geen ruimere toegang tot groepen of inhoud; gebruik de Server-API voor beheer op instantieniveau.

Gebruik de API-sleutel van het Loomio-gebruikersaccount dat de acties zal uitvoeren. Een apart botaccount is handig als een integratie geen uitnodigingen voor peilingen of meldingen moet ontvangen.

Ingelogde gebruikers kunnen hun API-sleutel en groeps-ID's vinden op de pagina voor API-toegang.

Stuur de API-sleutel mee in een Authorization: Bearer-header. API-sleutels in querystrings worden geweigerd omdat URL's kunnen worden vastgelegd door proxy's en toegangslogboeken.

Wijziging in authenticatie

De API-sleutel werd voorheen geaccepteerd als URL-parameter api_key. Verzoeken met ?api_key=YOUR_API_KEY werken niet meer. Gebruik in plaats daarvan de HTTP-header Authorization:

Authorization: Bearer YOUR_API_KEY

De voorbeelden gebruiken YOUR_API_KEY, groeps-ID 123 en https://www.loomio.com/. Vervang deze door jouw API-sleutel, groeps-ID en de URL van jouw Loomio-installatie.

Responsgrootte en gerelateerde records

Responsen van de Gebruikers-API gebruiken een samengesteld formaat: de primaire records worden aangevuld met gerelateerde records zoals topics, groepen, gebruikers, peilingen en emoji-reacties. Hiermee kan een client met één verzoek een lokale recordopslag vullen, maar de respons kan meer gegevens bevatten dan een eenvoudige integratie nodig heeft.

Geef compact=1 mee om omvangrijke gerelateerde topics, groepen, hoofdgroepen, lidmaatschappen, emoji-reacties, labels en vertalingen weg te laten. Primaire records en de gerelateerde records die nodig zijn om hun inhoud te interpreteren, blijven aanwezig.

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

Voor directe controle geef je exclude_types mee met recordtypen in het enkelvoud, gescheiden door spaties. Zo laat exclude_types=group reaction gerelateerde groepen en emoji-reacties weg. Veelgebruikte waarden zijn topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome en topic_item. Uitsluitingen gelden voor gerelateerde records, niet voor de primaire resource die via het endpoint wordt opgevraagd.

Responsen met collecties bevatten meta.total wanneer een exacte collectiegrootte is gedefinieerd. Het totaal wordt berekend voordat limit en offset worden toegepast. Endpoints zoals zoeken, die bewust een begrensde verzameling resultaten teruggeven, laten meta.total weg in plaats van null terug te geven.

Overzicht van endpoints

Groepen

Groepen opvragen

Geeft de groepen terug waarin de gebruiker van de API-sleutel een actief lidmaatschap heeft.

GET /api/b2/groups

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

De respons bevat alle overeenkomende records in een groups-array zonder paginering. Deze bevat hoofdgroepen en subgroepen, ook groepen waarvan het abonnement momenteel niet actief is. Controleer het veld enabled als een integratie alleen met ingeschakelde groepen moet werken.

Belangrijke groepsvelden zijn:

De respons kan aanvullende groepsinstellingen, gerelateerde records van hoofdgroepen en de lidmaatschappen van de API-gebruiker bevatten. Clients moeten velden die ze niet gebruiken negeren.

Een groep ophalen

Geeft één groep terug die zichtbaar is voor de gebruiker van de API-sleutel.

GET /api/b2/groups/:id_or_key_or_handle

De identificatie kan de numerieke ID, sleutel of identificatienaam van de groep zijn.

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

De respons bevat de groep in de groups-array en gebruikt dezelfde velden als het endpoint voor het opvragen van groepen. Een verzoek voor een groep waartoe de gebruiker van de API-sleutel geen toegang heeft, geeft een fout wegens onvoldoende rechten terug.

Webhooks

De Gebruikers-API werkt met verzoeken: een integratie roept Loomio aan wanneer deze gegevens wil lezen of wijzigen. Een groepswebhook zorgt voor verzending in de andere richting. Loomio stuurt geselecteerde groepsgebeurtenissen naar jouw endpoint zodra ze plaatsvinden, zodat een integratie de REST-API niet herhaaldelijk hoeft op te vragen om wijzigingen te vinden.

Webhooks worden per groep ingesteld en vereisen groepsbeheerdersrechten. Je kunt ze beheren via de Loomio-interface:

1. Open de groep.
2. Open het groepsmenu en selecteer Chatintegraties.
3. Voeg de integratie toe die overeenkomt met het payloadformaat dat jouw endpoint accepteert. Gebruik het Mattermost/Markdown-formaat voor een algemeen endpoint.
4. Voer een naam en de bestemmings-URL in.
5. Selecteer de gebeurtenissen die Loomio automatisch moet versturen.
6. Sla de integratie op en gebruik Test verbinding om een testbericht te versturen.

Gebruik een HTTPS-bestemming met een URL die niet te raden is. Loomio vereist dat de bestemming naar een openbaar adres verwijst en blokkeert verzoeken naar lokale of private netwerkadressen.

Agents en andere integraties kunnen webhooks ook beheren via de hieronder beschreven chatbot-endpoints met Bearer-authenticatie. De resource heet chatbots voor compatibiliteit met de chatintegraties van Loomio, maar vertegenwoordigt ook algemene uitgaande webhooks.

Webhooks opvragen

Geeft de chatintegraties terug die voor een groep zijn ingesteld. De gebruiker van de API-sleutel moet beheerder van die groep zijn. De respons bevat bestemmings-URL's en mag daarom niet toegankelijk worden gemaakt voor gewone groepsleden.

GET /api/b2/chatbots?group_id=123

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

De respons bevat een chatbots-array met deze velden:

Een webhook aanmaken

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

De gebruiker van de API-sleutel moet beheerder zijn van group_id. Voordat de bestemming wordt opgeslagen, wordt gecontroleerd of deze een openbare URL is.

Een webhook bijwerken

PATCH /api/b2/chatbots/:id

Stuur alle velden mee die moeten veranderen. Je kunt de webhook niet naar een andere groep verplaatsen door group_id te wijzigen.

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

Een webhookbestemming testen

Stuur een testbericht dat compatibel is met Markdown naar een bestemming voordat of nadat je de configuratie opslaat.

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

Een webhook verwijderen

DELETE /api/b2/chatbots/:id

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

Als je de configuratie verwijdert, worden er geen berichten meer afgeleverd. Er wordt geen inhoud uit de Loomio-groep verwijderd.

Gebeurtenistypen

Een webhook kan zich abonneren op deze gebeurtenistypen:

De webhook hoort bij één groep en ontvangt de gebeurtenissen uit die groep waarop hij is geabonneerd. Mensen kunnen de integratie ook expliciet selecteren bij het delen of verzenden van bepaalde meldingen, zelfs als de bijbehorende automatische gebeurtenis niet is geselecteerd.

HTTP-aflevering

Loomio verstuurt een asynchrone HTTP POST naar de ingestelde URL met deze header:

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

De time-out voor het verzoek is vijf seconden. Een 2xx-antwoord, inclusief 204 No Content, geldt als geslaagd. Diensten die webhooks ontvangen, moeten snel antwoorden, langer durend werk asynchroon verwerken en dubbele afleveringen of afleveringen in een andere volgorde kunnen verwerken.

Loomio voegt momenteel geen webhookhandtekening, header met een gedeeld geheim, gebeurtenis-ID of afleverings-ID toe. Behandel de volledige bestemmings-URL als een toegangsgegeven, maak deze niet openbaar en neem een niet te raden token op in de URL als de ontvangende dienst dat ondersteunt. Als je een stabiel, machineleesbaar gebeurtenisschema of ondertekende aflevering nodig hebt, gebruik de webhook dan als melding van een wijziging en haal de actuele records op via de geauthenticeerde Gebruikers-API.

Payloadformaten

Webhookpayloads zijn berichten die zijn opgemaakt voor weergave in chatdiensten. Het zijn geen volledige geserialiseerde Loomio-records. Links in het bericht verwijzen naar de betreffende Loomio-inhoud; een integratie kan vervolgens de Gebruikers-API gebruiken als deze gestructureerde gegevens over de actuele toestand nodig heeft.

Het algemene Markdown-formaat verstuurt bijvoorbeeld een berichtinhoud met deze structuur:

{
  "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"
}

De exacte berichttekst hangt af van de gebeurtenis, de taalinstelling van de groep, de instelling om alleen de melding te versturen en de Loomio-versie. Ontvangende diensten moeten uitgaan van de gedocumenteerde velden op het hoogste niveau van het gekozen formaat, in plaats van de formulering van zinnen te ontleden.

Zoeken

Zoek discussies, reacties, peilingen, stemmen en conclusies die zichtbaar zijn voor de gebruiker van de API-sleutel. De zoekresultaten bevatten openbare inhoud, ook als de gebruiker geen lid is van de bijbehorende groep; voor privé-inhoud blijven de normale zichtbaarheidsregels voor topics gelden.

GET /api/b2/search

Parameters

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

Het antwoord bevat een search_results-array. Elk zoekresultaat identificeert het overeenkomende record en de zichtbare context ervan met onder andere de velden searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at en tags. Velden die niet van toepassing zijn op een zoekresultaat, zijn null.

Deelnameverslag

Geef dezelfde samengevoegde deelnamegegevens terug die Loomio gebruikt voor het deelnameverslag.

GET /api/b2/reports

Parameters

Iemand is een afgevaardigde als die persoon in minstens één geselecteerde groep een actief lidmaatschap als afgevaardigde heeft. De aantallen voor die persoon worden over alle geselecteerde groepen samengevoegd. Rijen voor afgevaardigden worden ook teruggegeven als alle activiteitsaantallen nul zijn. De aantallen omvatten threads, reacties, peilingen, stemmen, conclusies en emoji-reacties; het zijn geen deelnamepercentages voor stemmen. Gebruikersrijen bevatten ook aantallen verstrekte, uitgebrachte en gemiste stembiljetten waarbij de identiteit van de stemmer bekend is. Anonieme peilingen worden uitgesloten van alle stemaantallen per persoon. all_votes_cast is alleen waar als er minstens één stembiljet is verstrekt en elk verstrekt stembiljet is uitgebracht.

De API past dezelfde zichtbaarheidsregels voor groepen toe als het verslag in de applicatie. Een API-sleutel van een gebruiker kan geen verslaggegevens beschikbaar maken uit groepen waartoe die gebruiker geen toegang heeft.

Voorbeeld

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'

De users-array bevat volledige activiteitsrijen:

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

Discussie aanmaken

Maak een discussie aan als de gebruiker van de API-sleutel.

POST /api/b2/discussions

Parameters

Voorbeeld

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

Discussie ophalen

Haal een discussie op met het discussie-ID, een geheel getal, of de sleutel, een tekenreeks.

GET /api/b2/discussions/:id

Voorbeeld

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

Discussies weergeven

Geef de discussies in een groep weer die zichtbaar zijn voor de gebruiker van de API-sleutel. Bij een openbaar zichtbare groep kan iemand die geen lid is de openbare discussies weergeven; privédiscussies blijven alleen toegankelijk voor gebruikers die ze in Loomio kunnen lezen.

GET /api/b2/discussions

Parameters

Voor compatibiliteit met oudere integraties worden per en from geaccepteerd als aliassen voor limit en offset. Ze blijven werken.

Voorbeeld

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

Threads weergeven

Geef de discussie- en peilingthreads weer die zichtbaar zijn voor de gebruiker van de API-sleutel, gesorteerd op meest recente activiteit. Het ID van een thread is het bijbehorende topic_id.

GET /api/b2/threads

Parameters

Voorbeeld

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

Thread lezen

Lees een thread, de bijbehorende geordende stroom van gebeurtenissen of het volledige zichtbare Markdown-document.

GET /api/b2/threads/:topic_id

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

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

Voorbeeld

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

Het endpoint items retourneert de geordende stroom van gebeurtenissen, inclusief zichtbare reacties, peilingen, stemmen en conclusies. Het endpoint markdown retourneert de volledige zichtbare thread als één Markdown-document. Redenen bij stemmen worden alleen opgenomen wanneer ze zichtbaar zijn voor de gebruiker van de API-sleutel.

Alle thread-endpoints handhaven dezelfde rechten als de Loomio-interface. De API-sleutel geeft geen toegang tot een thread die de gebruiker normaal gesproken niet kan openen.

Discussie bewerken

Bewerk een discussie als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet die discussie mogen bewerken.

PATCH /api/b2/discussions/:id

Parameters

Voorbeeld

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

Discussie logisch verwijderen

Verwijder een discussie logisch als de gebruiker van de API-sleutel. Hiermee wordt de discussie verwijderd, maar blijft het discussierecord bewaard.

DELETE /api/b2/discussions/:id

Voorbeeld

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

Reactie aanmaken

Maak een reactie aan in een discussie als de gebruiker van de API-sleutel.

POST /api/b2/comments

Parameters

Voorbeeld

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

Reactie bewerken

Bewerk een reactie als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet toestemming hebben om die reactie te bewerken.

PATCH /api/b2/comments/:id

Parameters

Voorbeeld

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

Reactie logisch verwijderen

Verwijder een reactie logisch als de gebruiker van de API-sleutel. Hiermee wordt de reactie verwijderd en de tekst verborgen, maar blijft het reactierecord bewaard.

DELETE /api/b2/comments/:id

Voorbeeld

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

Peiling aanmaken

Maak een peiling aan als de gebruiker van de API-sleutel.

POST /api/b2/polls

Parameters

Voorbeeld

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

Peiling ophalen

Haal een peiling op met het peiling-ID, een geheel getal, of de sleutel, een string.

GET /api/b2/polls/:id

Voorbeeld

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

Peilingen weergeven

Geef de peilingen in een groep weer die zichtbaar zijn voor de gebruiker van de API-sleutel. Bij een openbaar zichtbare groep kan iemand die geen lid is de openbare peilingen weergeven; privépeilingen blijven alleen toegankelijk voor gebruikers die ze in Loomio kunnen lezen. Het antwoord bevat de huidige conclusie van elke zichtbare peiling, zodat je met status=closed voorstellen kunt weergeven waarover een besluit is genomen.

GET /api/b2/polls

Parameters

Voor achterwaartse compatibiliteit worden per en from geaccepteerd als aliassen voor limit en offset. Ze blijven werken.

Voorbeeld

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

Peiling bewerken

Bewerk een peiling als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet die peiling mogen bewerken.

PATCH /api/b2/polls/:id

Parameters

Voorbeeld

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

Peiling logisch verwijderen

Verwijder een peiling logisch als de gebruiker van de API-sleutel. Hiermee wordt de peiling als verwijderd gemarkeerd en blijft het peilingrecord bewaard.

DELETE /api/b2/polls/:id

Voorbeeld

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

Lidmaatschappen weergeven

Geef de lidmaatschappen weer die zichtbaar zijn voor de gebruiker van de API-sleutel. Groepsleden kunnen de namen, ID's, titels en rollen van leden lezen. E-mailadressen worden alleen opgenomen voor het eigen account van de gebruiker van de API-sleutel of wanneer die gebruiker een groepsbeheerder is.

GET /api/b2/memberships

Parameters

Voorbeeld

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

Lidmaatschappen beheren

Stuur een lijst met e-mailadressen. Alle nieuwe e-mailadressen worden uitgenodigd voor de groep. Anders dan bij het weergeven van lidmaatschappen zijn voor deze handeling groepsbeheerdersrechten vereist.

POST /api/b2/memberships

Parameters

Voorbeeld

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

Als je remove_absent=1 meegeeft, worden alle leden van de groep die niet in de lijst staan uit de groep verwijderd. Let op: hiermee kun je iedereen uit jouw groep verwijderen.

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

Dit retourneert een object met {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.