A Loomio felhasználói API dokumentációja

A /api/b2 a Loomióval való integrációkhoz készült felhasználói API. Egy felhasználói fiók API-kulcsát használja, és minden műveletet az adott felhasználó nevében hajt végre.

A csoportműveleteknél az API-kulcs tulajdonosának tagságai és csoportjogosultságai érvényesek. A példányadminisztrátori szerepkör nem ad az API-kulcsnak további hozzáférést csoportokhoz vagy tartalmakhoz. A példány szintű adminisztrációhoz használd a Server API-t.

Annak a Loomio-fióknak az API-kulcsát használd, amelynek nevében a műveleteket végre szeretnéd hajtani. Külön botfiók hasznos, ha az integrációt nem szeretnéd szavazásokra meghívni, vagy nem szeretnéd, hogy értesítéseket kapjon.

Bejelentkezés után az API-kulcsodat és a csoportazonosítókat az API-hozzáférési oldalon találod.

Az API-kulcsot az Authorization: Bearer fejlécben küldd el. A lekérdezési karakterláncban megadott API-kulcsokat a rendszer elutasítja, mert az URL-eket a proxyk és a hozzáférési naplók rögzíthetik.

A hitelesítés változása

Korábban az API-kulcsot api_key URL-paraméterként is meg lehetett adni. A ?api_key=YOUR_API_KEY paramétert használó kérések már nem működnek. Helyette a HTTP Authorization fejlécet használd:

Authorization: Bearer YOUR_API_KEY

A példákban a YOUR_API_KEY API-kulcs, a 123 csoportazonosító és a https://www.loomio.com/ URL szerepel. Cseréld ki ezeket a saját API-kulcsodra, csoportazonosítódra és a Loomio-telepítésed URL-jére.

Válaszméret és kapcsolódó rekordok

A felhasználói API válaszai összetett formátumúak: az elsődleges rekordok mellett kapcsolódó rekordokat is tartalmaznak, például témákat, csoportokat, felhasználókat, szavazásokat és reakciókat. Így a kliens egyetlen kérésből feltöltheti a helyi rekordtárát, de a válasz több adatot tartalmazhat, mint amennyire egy egyszerű integrációnak szüksége van.

A compact=1 paraméterrel kihagyhatod a nagy méretű kapcsolódó témákat, csoportokat, szülőcsoportokat, tagságokat, reakciókat, címkéket és fordításokat. Az elsődleges rekordok és a tartalmuk értelmezéséhez szükséges kapcsolódó rekordok megmaradnak.

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

Ha pontosan szeretnéd szabályozni a választ, add meg az exclude_types paraméterben az egyes számú rekordtípusokat szóközzel elválasztva. Például az exclude_types=group reaction kihagyja a kapcsolódó csoportokat és reakciókat. Gyakori értékek: topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome és topic_item. A kizárás a kapcsolódó rekordokra vonatkozik, nem a végponttól kért elsődleges erőforrásra.

A gyűjteményt visszaadó válaszok tartalmazzák a meta.total értéket, ha a gyűjtemény pontos mérete meghatározható. Az összesítést a limit és az offset alkalmazása előtt számítja ki a rendszer. Azok a végpontok, például a keresés, amelyek szándékosan korlátozott eredményhalmazt adnak vissza, kihagyják a meta.total mezőt ahelyett, hogy null értéket adnának vissza.

Végpontok áttekintése

Csoportok

Csoportok listázása

Azoknak a csoportoknak a lekérése, amelyekben az API-kulcs tulajdonosának aktív tagsága van.

GET /api/b2/groups

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

A válasz az összes megfelelő rekordot tartalmazza egy lapozás nélküli groups tömbben. Szülőcsoportok és alcsoportok is szerepelnek benne, köztük olyan csoportok is, amelyek előfizetése jelenleg nem aktív. Ellenőrizd az enabled mezőt, ha az integrációnak csak aktív csoportokkal szabad működnie.

A fontosabb csoportmezők:

A válasz további csoportbeállításokat, kapcsolódó szülőcsoport-rekordokat és az API-felhasználó tagságait is tartalmazhatja. A kliensek hagyják figyelmen kívül a nem használt mezőket.

Csoport lekérése

Az API-kulcs tulajdonosa számára látható csoport lekérése.

GET /api/b2/groups/:id_or_key_or_handle

Az azonosító lehet a csoport numerikus azonosítója, kulcsa vagy olvasható azonosítója.

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

A válasz a groups tömbben tartalmazza a csoportot, ugyanazokkal a mezőkkel, mint a listázó végpont. Ha az API-kulcs tulajdonosa nem fér hozzá a kért csoporthoz, a kérés jogosultsági hibát ad vissza.

Webhookok

A felhasználói API kérésekre válaszol: az integráció akkor hívja meg a Loomiót, amikor adatot szeretne olvasni vagy módosítani. A csoport webhookja az ellenkező irányban továbbít adatot. A Loomio a kiválasztott csoporteseményeket az előfordulásukkor elküldi a végpontodra, így az integrációnak nem kell rendszeresen lekérdeznie a REST API-t a változásokért.

A webhookokat csoportonként kell beállítani, és kezelésükhöz csoportadminisztrátori jogosultság szükséges. A Loomio felületén így kezelheted őket:

1. Nyisd meg a csoportot.
2. Nyisd meg a csoport menüjét, és válaszd a Csevegési integrációk lehetőséget.
3. Add hozzá azt az integrációt, amelynek adatformátumát a végpontod fogadni tudja. Általános célú végponthoz használd a Mattermost/Markdown formátumot.
4. Adj meg egy nevet és a cél URL-t.
5. Válaszd ki azokat az eseményeket, amelyeket a Loomio automatikusan elküldjön.
6. Mentsd az integrációt, majd a Kapcsolat tesztelése lehetőséggel küldj tesztüzenetet.

Olyan HTTPS-címet használj célként, amelynek URL-je nem található ki könnyen. A Loomio megköveteli, hogy a cél nyilvános címre mutasson, és blokkolja a helyi vagy magánhálózati címekre irányuló kéréseket.

Az ügynökök és más integrációk az alább ismertetett, Bearer-hitelesítést használó chatbotvégpontokon keresztül is kezelhetik a webhookokat. Az erőforrás neve chatbots, hogy kompatibilis legyen a Loomio csevegési integrációival, de általános kimenő webhookokat is jelöl.

Webhookok listázása

Egy csoporthoz beállított csevegési integrációk lekérése. Az API-kulcs tulajdonosának a csoport adminisztrátorának kell lennie. A válasz tartalmazza a cél URL-eket, ezért nem szabad elérhetővé tenni a csoport többi tagja számára.

GET /api/b2/chatbots?group_id=123

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

A válasz egy chatbots tömböt tartalmaz a következő mezőkkel:

Webhook létrehozása

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

Az API-kulcshoz tartozó felhasználónak a group_id által jelölt csoport adminisztrátorának kell lennie. Mentés előtt a rendszer ellenőrzi, hogy a cél nyilvánosan elérhető URL-e.

Webhook frissítése

PATCH /api/b2/chatbots/:id

Küldd el a módosítani kívánt mezőket. A group_id módosításával nem helyezheted át a webhookot másik csoportba.

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

Webhook céljának tesztelése

A beállítások mentése előtt vagy után küldj a cél címére egy Markdown-kompatibilis tesztüzenetet.

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 törlése

DELETE /api/b2/chatbots/:id

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

A beállítás törlése leállítja a későbbi kézbesítéseket. A Loomio-csoport tartalmát nem törli.

Eseménytípusok

A webhook ezekre az eseménytípusokra iratkozhat fel:

A webhook egy csoporthoz tartozik, és annak feliratkozott eseményeit fogadja. Az integrációt az emberek egyes értesítések megosztásakor vagy küldésekor külön is kiválaszthatják, akkor is, ha a megfelelő automatikus esemény nincs kiválasztva.

HTTP-kézbesítés

A Loomio aszinkron HTTP POST kérést küld a beállított URL-re ezzel a fejléccel:

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

A kérés időkorlátja öt másodperc. A rendszer minden 2xx választ sikeresnek tekint, beleértve a 204 No Content választ is. A webhookot fogadó szolgáltatás válaszoljon gyorsan, a hosszabb feladatokat dolgozza fel aszinkron módon, és kezelje a többször vagy eltérő sorrendben érkező kézbesítéseket.

A Loomio jelenleg nem ad a webhookhoz aláírást, közös titkot tartalmazó fejlécet, eseményazonosítót vagy kézbesítési azonosítót. A teljes cél-URL-t kezeld hozzáférési adatként, ne tedd nyilvánossá, és használj benne nehezen kitalálható tokent, ha a fogadó szolgáltatás ezt támogatja. Ha állandó, géppel feldolgozható eseménysémára vagy aláírt kézbesítésre van szükséged, használd a webhookot változásjelzésként, majd kérd le az aktuális rekordokat a hitelesített felhasználói API-n keresztül.

Adatformátumok

A webhookok csevegőszolgáltatásoknak szánt üzeneteket küldenek. Ezek nem teljes Loomio-rekordok. Az üzenetben lévő hivatkozások megmutatják, melyik Loomio-tartalmat érinti az esemény. Ha az integrációnak strukturált, aktuális adatokra van szüksége, lekérheti őket a felhasználói API-n keresztül.

Az általános Markdown-formátum például ilyen szerkezetű üzenettörzset küld:

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

Az üzenet pontos szövege az eseménytől, a csoport nyelvi beállításától, a csak értesítést tartalmazó beállítástól és a Loomio verziójától függ. Az üzenetet fogadó szolgáltatás a választott formátum dokumentált felső szintű mezőire támaszkodjon az egyes mondatok elemzése helyett.

Keresés

Keress az API-kulcshoz tartozó felhasználó számára látható beszélgetések, hozzászólások, szavazások, leadott szavazatok és következtetések között. A találatok között nyilvános tartalom is szerepelhet olyan csoportból, amelynek a felhasználó nem tagja. A privát tartalmakra a témák szokásos láthatósági szabályai vonatkoznak.

GET /api/b2/search

Paraméterek

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

A válasz egy search_results tömböt tartalmaz. Minden találat azonosítja az egyező rekordot és annak látható környezetét. A mezők között szerepel a searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at és tags. Az adott találatra nem vonatkozó mezők értéke null.

Részvételi jelentés

A Loomio Részvételi jelentésében használt összesített részvételi adatokat adja vissza.

GET /api/b2/reports

Paraméterek

Valaki akkor küldött, ha a kiválasztott csoportok bármelyikében aktív küldötti tagsága van. A rendszer az összes kiválasztott csoportból összesíti az adatait. A küldöttek akkor is szerepelnek a jelentésben, ha minden tevékenységi számuk nulla. A számok a témákat, hozzászólásokat, szavazásokat, leadott szavazatokat, következtetéseket és reakciókat fedik le; nem a szavazási részvételi arányt mutatják. A felhasználói sorok a névhez kötött szavazólapok kiadott, leadott és elmulasztott számát is tartalmazzák. Az anonim szavazások minden személyenkénti szavazatszámból kimaradnak. Az all_votes_cast csak akkor igaz, ha legalább egy szavazólapot kiadtak, és mindegyiket leadták.

Az API ugyanazokat a csoportláthatósági szabályokat alkalmazza, mint a Loomio felületén elérhető jelentés. A felhasználói API-kulcs nem teszi elérhetővé azoknak a csoportoknak a jelentésadatait, amelyekhez a felhasználó nem fér hozzá.

Példa

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'

A users tömb teljes tevékenységi sorokat tartalmaz:

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

Beszélgetés létrehozása

Hozz létre egy beszélgetést az API-kulcshoz tartozó felhasználóként.

POST /api/b2/discussions

Paraméterek

Példa

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

Beszélgetés lekérése

Kérj le egy beszélgetést a számmal megadott azonosítója vagy a szöveges kulcsa alapján.

GET /api/b2/discussions/:id

Példa

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

Beszélgetések listázása

Listázd az API-kulcshoz tartozó felhasználó számára látható beszélgetéseket egy csoportban. Nyilvánosan látható csoport esetén a csoporton kívüli felhasználó is listázhatja a nyilvános beszélgetéseket. A privát beszélgetéseket csak azok érhetik el, akik a Loomióban is olvashatják őket.

GET /api/b2/discussions

Paraméterek

Korábbi paraméterek: a per és a from továbbra is használható a limit, illetve az offset helyett.

Példa

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

Témák listázása

Listázd az API-kulcshoz tartozó felhasználó számára látható beszélgetések és szavazások témáit, a legutóbbi aktivitás szerint rendezve. A téma azonosítója a topic_id.

GET /api/b2/threads

Paraméterek

Példa

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

Téma olvasása

Olvasd el a témát, az eseményeinek rendezett sorát vagy a teljes látható tartalmát Markdown-dokumentumként.

GET /api/b2/threads/:topic_id

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

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

Példa

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

Az items végpont az eseményeket sorrendben adja vissza, beleértve a látható hozzászólásokat, szavazásokat, leadott szavazatokat és következtetéseket. A markdown végpont a téma teljes látható tartalmát egyetlen Markdown-dokumentumként adja vissza. A szavazatok indoklása csak akkor szerepel benne, ha látható az API-kulcshoz tartozó felhasználó számára.

Minden témához tartozó végpont ugyanazokat a jogosultságokat érvényesíti, mint a Loomio felülete. Az API-kulcs nem ad hozzáférést olyan témához, amelyet a felhasználó egyébként nem nyithat meg.

Beszélgetés szerkesztése

Szerkessz egy beszélgetést az API-kulcshoz tartozó felhasználóként. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie a beszélgetés szerkesztésére.

PATCH /api/b2/discussions/:id

Paraméterek

Példa

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

Beszélgetés logikai törlése

Törölj logikailag egy beszélgetést az API-kulcshoz tartozó felhasználóként. A beszélgetés törölt állapotba kerül, de a rekordja megmarad.

DELETE /api/b2/discussions/:id

Példa

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

Hozzászólás létrehozása

Hozz létre egy hozzászólást egy beszélgetésben az API-kulcshoz tartozó felhasználóként.

POST /api/b2/comments

Paraméterek

Példa

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

Hozzászólás szerkesztése

Szerkessz egy hozzászólást az API-kulcshoz tartozó felhasználóként. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie a hozzászólás szerkesztésére.

PATCH /api/b2/comments/:id

Paraméterek

Példa

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

Hozzászólás logikai törlése

Törölj logikailag egy hozzászólást az API-kulcshoz tartozó felhasználóként. A hozzászólás szövege rejtetté válik, de a rekordja megmarad.

DELETE /api/b2/comments/:id

Példa

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

Szavazás létrehozása

Hozz létre szavazást az API-kulcshoz tartozó felhasználóként.

POST /api/b2/polls

Paraméterek

Példa

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

Szavazás megtekintése

Kérj le egy szavazást a számmal megadott azonosítója vagy a szöveges kulcsa alapján.

GET /api/b2/polls/:id

Példa

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

Szavazások listázása

Listázd azokat a csoportbeli szavazásokat, amelyeket az API-kulcshoz tartozó felhasználó láthat. Nyilvánosan látható csoport esetén egy nem tag felhasználó is listázhatja a nyilvános szavazásokat. A privát szavazásokat csak azok érhetik el, akik a Loomióban is megtekinthetik őket. A válasz minden látható szavazás aktuális következtetését tartalmazza, így a status=closed használatával listázhatod a lezárt javaslatokat.

GET /api/b2/polls

Paraméterek

Korábbi paraméterek: a per és a from továbbra is használható a limit, illetve az offset helyett.

Példa

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

Szavazás szerkesztése

Szerkessz egy szavazást az API-kulcshoz tartozó felhasználóként. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie a szavazás szerkesztésére.

PATCH /api/b2/polls/:id

Paraméterek

Példa

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

Szavazás törlése visszaállítási lehetőséggel

Törölj egy szavazást visszaállítási lehetőséggel az API-kulcshoz tartozó felhasználóként. A szavazás kikerül a használatból, de a rekordja megmarad.

DELETE /api/b2/polls/:id

Példa

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

Tagságok listázása

Listázd az API-kulcshoz tartozó felhasználó számára látható tagságokat. A csoporttagok láthatják a tagok nevét, azonosítóját, beosztását és szerepkörét. Az e-mail-címek csak az API-kulcshoz tartozó felhasználó saját fiókjánál jelennek meg, vagy akkor, ha a felhasználó a csoport adminisztrátora.

GET /api/b2/memberships

Paraméterek

Példa

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

Tagságok kezelése

Küldj el egy e-mail-címeket tartalmazó listát. Az új címek tulajdonosai meghívást kapnak a csoportba. A tagságok listázásával ellentétben ehhez a művelethez csoportadminisztrátori jogosultság szükséges.

POST /api/b2/memberships

Paraméterek

Példa

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

Ha megadod a remove_absent=1 értéket, a rendszer eltávolítja a csoportból azokat a tagokat, akik nem szerepelnek a listán. Légy óvatos: akár a csoport összes tagját is eltávolíthatod.

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

A válasz egy objektum: {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.