Documentatie voor de Loomio Gebruikers-API

/api/b2 is de API voor integraties met Loomio die namens een gebruiker werken. De API gebruikt de API-sleutel van een gebruikersaccount en voert elke handeling uit als die gebruiker.

Voor groepshandelingen gelden de lidmaatschappen en groepsrechten van de gebruiker bij de API-sleutel. Beheerdersrechten voor de installatie geven een API-sleutel geen extra toegang tot groepen of inhoud. Gebruik de Server API voor beheer op installatieniveau.

Gebruik de API-sleutel van het Loomio-account waarmee de handelingen moeten worden uitgevoerd. Een apart botaccount is handig als de integratie geen uitnodigingen voor peilingen of meldingen moet ontvangen.

Als je bent ingelogd, vind je jouw API-sleutel en groeps-ID's op de pagina voor API-toegang.

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

Wijziging in authenticatie

Voorheen werd de API-sleutel 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.

Omvang van antwoorden en gerelateerde records

Antwoorden van de Gebruikers-API hebben een samengesteld formaat: de hoofdrecords worden geleverd met gerelateerde records, zoals onderwerpen, groepen, gebruikers, peilingen en reacties. Zo kan een client met één verzoek een lokale verzameling records vullen. Het antwoord kan daardoor meer gegevens bevatten dan een eenvoudige integratie nodig heeft.

Geef compact=1 mee om omvangrijke gerelateerde onderwerpen, groepen, bovenliggende groepen, lidmaatschappen, reacties, tags en vertalingen weg te laten. De hoofdrecords en de gerelateerde records die nodig zijn om hun inhoud te begrijpen, blijven aanwezig.

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

Voor meer controle geef je exclude_types mee met enkelvoudige recordtypen, gescheiden door spaties. Met exclude_types=group reaction laat je bijvoorbeeld gerelateerde groepen en 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 hoofdresource die je via het endpoint opvraagt.

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

Overzicht van endpoints

Groepen

Groepen tonen

Geef de groepen terug waarvan de gebruiker bij de API-sleutel actief lid is.

GET /api/b2/groups

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

Het antwoord bevat alle overeenkomende records in een groups-array zonder paginering. Deze omvat bovenliggende groepen en subgroepen, ook als hun abonnement momenteel niet actief is. Controleer het veld enabled als een integratie alleen voor ingeschakelde groepen mag werken.

Belangrijke groepsvelden zijn:

Het antwoord kan aanvullende groepsinstellingen, gerelateerde records van bovenliggende groepen en de lidmaatschappen van de API-gebruiker bevatten. Clients kunnen velden die ze niet gebruiken negeren.

Een groep ophalen

Geef één groep terug die zichtbaar is voor de gebruiker bij de API-sleutel.

GET /api/b2/groups/:id_or_key_or_handle

Als identificatie kun je de numerieke ID, sleutel of aanduiding van de groep gebruiken.

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

Het antwoord bevat de groep in de groups-array en gebruikt dezelfde velden als het endpoint voor de groepslijst. Een verzoek om een groep waartoe de gebruiker bij de API-sleutel geen toegang heeft, geeft een rechtenfout.

Webhooks

De Gebruikers-API werkt op basis van verzoeken: een integratie roept Loomio aan wanneer ze gegevens wil lezen of wijzigen. Met een groepswebhook stuurt Loomio gegevens de andere kant op. Loomio stuurt geselecteerde groepsgebeurtenissen naar jouw endpoint zodra ze plaatsvinden. Daardoor hoeft een integratie de REST API niet regelmatig op wijzigingen te controleren.

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

1. Open de groep.
2. Open het groepsmenu en selecteer Chatintegraties.
3. Voeg de integratie toe waarvan jouw endpoint het gegevensformaat accepteert. Gebruik voor een algemeen endpoint het formaat Mattermost/Markdown.
4. Voer een naam en de doel-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 privénetwerkadressen.

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

Webhooks tonen

Geef de chatintegraties terug die voor een groep zijn ingesteld. De gebruiker bij de API-sleutel moet beheerder van die groep zijn. Het antwoord bevat doel-URL's en mag daarom niet toegankelijk zijn 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'

Het antwoord bevat een chatbots-array met deze velden:

Een webhook maken

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 doel-URL wordt opgeslagen, wordt gecontroleerd of deze openbaar is.

Een webhook bijwerken

PATCH /api/b2/chatbots/:id

Stuur de velden die je wilt wijzigen. 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 geschikt is voor Markdown naar de 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 nieuwe berichten meer afgeleverd. Inhoud van de Loomio-groep blijft behouden.

Gebeurtenistypen

Een webhook kan zich op deze gebeurtenistypen abonneren:

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

HTTP-aflevering

Loomio verstuurt asynchroon een 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, waaronder 204 No Content, geldt als geslaagd. Ontvangers van webhooks moeten snel antwoorden, langer durend werk asynchroon verwerken en kunnen omgaan met dubbele of in een andere volgorde afgeleverde berichten.

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

Payloadformaten

Webhookpayloads zijn berichten voor chatdiensten. Ze bevatten geen volledige geserialiseerde Loomio-gegevens. De links in een bericht verwijzen naar de betrokken inhoud in Loomio. Een integratie kan daarna via de gebruikers-API de actuele gegevens in gestructureerde vorm ophalen.

Het algemene Markdown-formaat verstuurt bijvoorbeeld een bericht 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 voor alleen meldingen en de Loomio-versie. Gebruik als ontvanger de gedocumenteerde velden op het hoogste niveau van het gekozen formaat. Leid gegevens niet af uit de formulering van zinnen.

Zoeken

Zoek in discussies, reacties, peilingen, stemmen en conclusies die zichtbaar zijn voor de gebruiker van de API-sleutel. De resultaten bevatten ook openbare inhoud van groepen waarvan de gebruiker geen lid is. Voor privé-inhoud gelden de normale zichtbaarheidregels voor topics.

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 array met search_results. Elk resultaat vermeldt het gevonden record en de zichtbare context ervan, met onder meer 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 resultaat, hebben de waarde null.

Deelnameverslag

Geeft dezelfde samengevoegde deelnamegegevens terug die Loomio in het deelnameverslag gebruikt.

GET /api/b2/reports

Parameters

Iemand is een afgevaardigde als die persoon in een van de geselecteerde groepen een actief lidmaatschap als afgevaardigde heeft. De aantallen worden over alle geselecteerde groepen samengevoegd. Afgevaardigden worden ook getoond als alle activiteitsaantallen nul zijn. De aantallen omvatten discussies, reacties, peilingen, stemmen, conclusies en emoji-reacties. Het zijn geen percentages voor deelname aan stemmingen. De rijen per gebruiker bevatten ook aantallen toegewezen, uitgebrachte en gemiste stemmen bij niet-anonieme stemmingen. Anonieme peilingen tellen niet mee in de stemtotalen per persoon. all_votes_cast is alleen waar als minstens één stem is toegewezen en alle toegewezen stemmen zijn uitgebracht.

De API past dezelfde regels voor groepszichtbaarheid toe als het verslag in Loomio. Een sleutel voor de gebruikers-API kan geen verslaggegevens tonen van groepen waartoe de 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 array users bevat volledige rijen met activiteitsgegevens:

{
  "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 namens 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 de numerieke discussie-ID of de sleutel als 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 ook iemand die geen lid is de openbare discussies weergeven. Privédiscussies blijven alleen zichtbaar voor gebruikers die ze in Loomio kunnen lezen.

GET /api/b2/discussions

Parameters

Voor compatibiliteit blijven per en from werken als alternatieve namen voor limit en offset.

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 recentste activiteit. De ID van een thread is de 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 gebeurtenissen in volgorde 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 items-endpoint geeft de gebeurtenissen in volgorde terug, waaronder zichtbare reacties, peilingen, stemmen en conclusies. Het markdown-endpoint geeft de volledige zichtbare thread terug als één Markdown-document. Redenen voor stemmen worden alleen opgenomen als ze zichtbaar zijn voor de gebruiker van de API-sleutel.

Voor alle thread-endpoints gelden dezelfde toegangsrechten als in Loomio. Een API-sleutel geeft geen toegang tot een thread die de gebruiker normaal niet kan openen.

Discussie bewerken

Bewerk een discussie namens de gebruiker van de API-sleutel. Dezelfde toegangsrechten gelden als in Loomio: de gebruiker moet deze 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 voorlopig verwijderen

Verwijder een discussie voorlopig namens de gebruiker van de API-sleutel. De discussie wordt weggehaald, maar het discussierecord blijft 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

Plaats een reactie in een discussie namens 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 namens de gebruiker van de API-sleutel. Dezelfde toegangsrechten gelden als in Loomio: de gebruiker moet deze reactie mogen 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 voorlopig verwijderen

Verwijder een reactie voorlopig namens de gebruiker van de API-sleutel. De reactie wordt weggehaald en de tekst wordt verborgen, maar het reactierecord blijft 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 maken

Maak een peiling aan namens 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 numerieke peiling-ID of de sleutel als tekst.

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 de gebruiker van de API-sleutel kan zien. Bij een openbaar zichtbare groep kunnen ook niet-leden de openbare peilingen weergeven. Privépeilingen blijven beperkt tot gebruikers die ze in Loomio kunnen lezen. Het antwoord bevat de huidige conclusie van elke zichtbare peiling. Gebruik status=closed om voorstellen met een conclusie weer te geven.

GET /api/b2/polls

Parameters

Voor compatibiliteit blijven per en from werken als alternatieve namen voor limit en offset.

Voorbeeld

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

Peiling bewerken

Bewerk een peiling namens de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet de 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 verwijderen zonder het record te wissen

Verwijder een peiling namens de gebruiker van de API-sleutel zonder het record te wissen. De peiling wordt verwijderd, maar het peilingrecord blijft bestaan.

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 de gebruiker van de API-sleutel kan zien. Groepsleden kunnen namen, ID's, titels en rollen van leden lezen. E-mailadressen zijn alleen opgenomen voor het eigen account van de gebruiker van de API-sleutel of wanneer die gebruiker 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

Verstuur een lijst met e-mailadressen. Nieuwe adressen op de lijst krijgen een uitnodiging voor de groep. Hiervoor zijn beheerdersrechten voor de groep 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 opgeeft, worden alle groepsleden die niet op de lijst staan uit de groep verwijderd. Controleer de lijst zorgvuldig: je kunt hiermee 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 geeft een object terug met {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.