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

A /api/b2 a Loomio-integrációk felhasználói API-ja. 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űveletek az API-kulcshoz tartozó felhasználó tagságait és csoportjogosultságait használják. A példányadminisztrátori szerepkör nem bővíti az API-kulcs hozzáférését a csoportokhoz vagy tartalmakhoz; a példányszintű adminisztrációhoz használd a szerver API-t.

Annak a Loomio-felhasználói fióknak az API-kulcsát használd, amely a műveleteket végrehajtja. Egy külön botfiók hasznos, ha az integrációnak nem kell meghívókat kapnia szavazásokhoz vagy értesítéseket fogadnia.

A bejelentkezett felhasználók az API-hozzáférési oldalon találják meg az API-kulcsukat és a csoportazonosítóikat.

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

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 használd a HTTP Authorization fejlécét:

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 le ezeket a saját API-kulcsodra, csoportazonosítódra és Loomio-telepítésed URL-jére.

A válasz mérete és a kapcsolódó rekordok

A felhasználói API válaszai összetett formátumot használnak: az elsődleges rekordokat kapcsolódó rekordok, például témák, csoportok, felhasználók, szavazások és reakciók kísérik. Így a kliens egyetlen kérésből feltölthet egy helyi rekordtárat, de a válasz több adatot is tartalmazhat, mint amennyire egy egyszerű integrációnak szüksége van.

Add meg a compact=1 paramétert a nagy méretű kapcsolódó témák, csoportok, szülőcsoportok, tagságok, reakciók, címkék és fordítások kihagyásához. Az elsődleges rekordok és a tartalmuk értelmezéséhez szükséges kapcsolódó rekordok továbbra is szerepelnek a válaszban.

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

A közvetlen szabályozáshoz add meg az exclude_types paramétert szóközzel elválasztott, egyes számú rekordtípusokkal. 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ások a kapcsolódó rekordokra vonatkoznak, nem a végponttól kért elsődleges erőforrásra.

A gyűjteményeket visszaadó válaszok tartalmazzák a meta.total mezőt, ha a gyűjtemény pontos mérete meghatározott. A teljes elemszám kiszámítása a limit és az offset alkalmazása előtt történik. 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.

A végpontok áttekintése

Csoportok

Csoportok listázása

Visszaadja azokat a csoportokat, amelyekben az API-kulcshoz tartozó felhasználó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 egy nem lapozott groups tömbben tartalmazza. Szülőcsoportokat és alcsoportokat is tartalmaz, köztük olyan csoportokat, amelyek előfizetése jelenleg nem aktív. Ellenőrizd az enabled mezőt, ha az integrációnak csak engedélyezett csoportokkal kell működnie.

A fontosabb csoportmezők:

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

Csoport lekérése

Visszaad egy, az API-kulcshoz tartozó felhasználó számára látható csoportot.

GET /api/b2/groups/:id_or_key_or_handle

Az azonosító lehet a csoport numerikus azonosítója, kulcsa vagy ember számára 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, és ugyanazokat a mezőket használja, mint a listázási végpont. Ha az API-kulcshoz tartozó felhasználó 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ésalapú: az integráció akkor hívja meg a Loomiót, amikor adatot szeretne olvasni vagy módosítani. A csoport webhookja lehetővé teszi az ellenkező irányú adatküldést. A Loomio a kiválasztott csoporteseményeket a bekövetkezésükkor 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 ehhez 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 ki a Csevegési integrációk lehetőséget.
3. Add hozzá a végpontod által fogadott üzenetformátumnak megfelelő integrációt. Általános célú végponthoz használd a Mattermost/Markdown formátumot.
4. Adj meg egy nevet és a cél URL-jét.
5. Válaszd ki azokat az eseményeket, amelyeket a Loomio automatikusan küldjön el.
6. Mentsd el az integrációt, majd a Kapcsolat tesztelése lehetőséggel küldj egy tesztüzenetet.

Használj HTTPS-célcímet nem kitalálható URL-lel. A Loomio megköveteli, hogy a cél nyilvános címre oldódjon fel, és blokkolja a helyi vagy privát hálózati címekre irányuló kéréseket.

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

Webhookok listázása

Visszaadja a csoporthoz beállított csevegési integrációkat. Az API-kulcshoz tartozó felhasználónak a csoport adminisztrátorának kell lennie. A válasz cél-URL-eket tartalmaz, ezért nem tehető hozzáférhetővé a csoport egyszerű tagjai 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 az alábbi 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 megadott csoport adminisztrátorának kell lennie. Mentés előtt a rendszer ellenőrzi, hogy a cél nyilvános URL-e.

Webhook frissítése

PATCH /api/b2/chatbots/:id

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

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élcímének tesztelése

Küldj Markdown-kompatibilis tesztüzenetet a célcímre a beállítások mentése előtt vagy után.

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 konfiguráció törlése leállítja a további kézbesítéseket. A Loomio-csoport tartalmát nem törli.

Eseménytípusok

Egy webhook a következő eseménytípusokra iratkozhat fel:

A webhook egy csoporthoz tartozik, és ebből a csoportból kapja meg azokat az eseményeket, amelyekre feliratkozott. Megosztáskor vagy egyes értesítések küldésekor az emberek külön is kiválaszthatják az integrációt, 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 2xx válasz sikeresnek számít, beleértve a 204 No Content választ is. A webhookot fogadó szolgáltatások válaszoljanak gyorsan, a hosszabb feladatokat aszinkron módon dolgozzák fel, és kezeljék az ismétlődő vagy eltérő sorrendben érkező kézbesítéseket.

A Loomio jelenleg nem ad hozzá webhook-aláírást, közös titkot tartalmazó fejlécet, eseményazonosítót vagy kézbesítési azonosítót. Kezeld a teljes cél-URL-t hitelesítő adatként, ne tedd nyilvánossá, és helyezz el benne egy kitalálhatatlan tokent, ha a fogadó szolgáltatás ezt támogatja. Ha stabil, géppel olvasható eseménysémára vagy aláírt kézbesítésre van szükséged, használd a webhookot változásértesítésként, és kérd le az aktuális rekordokat a hitelesített Felhasználói API-n keresztül.

Adatformátumok

A webhookok által küldött adatok csevegőszolgáltatásokban való megjelenítésre szánt üzenetek. Nem teljes, szerializált Loomio-rekordok. Az üzenetben található hivatkozások azonosítják az érintett Loomio-tartalmat; az integráció a Felhasználói API-n keresztül kérhet további adatokat, ha strukturált formában van szüksége az aktuális állapotra.

Az általános Markdown-formátum például ilyen szerkezetű tö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 küldő beállítástól és a Loomio verziójától függ. A fogadó szolgáltatások a kiválasztott formátum dokumentált legfelső szintű mezőire támaszkodjanak a mondatok szövegének 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, szavazatok és következtetések között. Az eredmények akkor is tartalmaznak nyilvános tartalmat, ha a felhasználó nem tagja az adott csoportnak; a privát tartalomra továbbra is a szálak 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 többek között a következő mezőkkel: searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at és tags. A találatra nem vonatkozó mezők értéke null.

Részvételi jelentés

Ugyanazokat az összesített részvételi adatokat adja vissza, amelyeket a Loomio részvételi jelentése használ.

GET /api/b2/reports

Paraméterek

Egy személy akkor számít küldöttnek, ha bármelyik kiválasztott csoportban aktív küldötti tagsággal rendelkezik. A hozzá tartozó darabszámokat az összes kiválasztott csoportból összesíti. A küldöttek sorait akkor is visszaadja, ha minden tevékenység darabszáma nulla. A darabszámok a szálakat, hozzászólásokat, szavazásokat, szavazatokat, következtetéseket és reakciókat fedik le; nem a szavazási részvétel arányát mutatják. A felhasználók sorai az azonosított szavazásokban kiadott, leadott és elmulasztott szavazólapok számát is tartalmazzák. A névtelen szavazások kimaradnak minden személyenkénti szavazati darabszámból. Az all_votes_cast csak akkor igaz, ha legalább egy szavazólapot kiadtak, és minden kiadott szavazólapot leadtak.

Az API ugyanazokat a csoportláthatósági szabályokat alkalmazza, mint az alkalmazásban elérhető jelentés. Egy felhasználói API-kulcs nem teheti elérhetővé olyan csoportok 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 a tevékenységi adatokat tartalmazó teljes sorokat adja vissza:

{
  "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 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 az egész számként megadott azonosítójával vagy a szövegként megadott kulcsával.

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 egy csoportnak az API-kulcshoz tartozó felhasználó számára látható beszélgetéseit. Nyilvánosan látható csoport esetén a nem tagok is listázhatják a nyilvános beszélgetéseket; a privát beszélgetésekhez továbbra is csak azok a felhasználók férhetnek hozzá, akik a Loomióban is olvashatják őket.

GET /api/b2/discussions

Paraméterek

Korábbi paraméterek: a per és a from a limit és az offset alternatív neveként használható, és továbbra is működni fog.

Példa

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

Szálak listázása

Listázd az API-kulcshoz tartozó felhasználó számára látható beszélgetési és szavazási szálakat a legutóbbi aktivitás szerint rendezve. A szál azonosítója a topic_id értéke.

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'

Szál olvasása

Olvasd el a szálat, annak rendezett eseményfolyamát vagy teljes látható Markdown-dokumentumát.

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 a rendezett eseményfolyamot adja vissza, beleértve a látható hozzászólásokat, szavazásokat, szavazatokat és következtetéseket. A markdown végpont a teljes látható szálat egyetlen Markdown-dokumentumként adja vissza. A szavazatok indoklásai csak akkor szerepelnek benne, ha láthatók az API-kulcshoz tartozó felhasználó számára.

Minden szálvégpont ugyanazokat a jogosultságokat érvényesíti, mint a Loomio felülete. Az API-kulcs nem biztosít hozzáférést olyan szálhoz, 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ó nevében. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie az adott 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ó nevében. Ez eltávolítja a beszélgetést, de megőrzi a beszélgetés adatbázisrekordját.

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ó nevében.

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ó nevében. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie az adott 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ó nevében. Ez eltávolítja a hozzászólást és elrejti a szövegét, de megőrzi a hozzászólás adatbázisrekordját.

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 egy szavazást az API-kulcshoz tartozó felhasználó nevében.

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 lekérése

Kérj le egy szavazást az egész számként megadott azonosítójával vagy a karakterláncként megadott kulcsával.

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 egy csoport szavazásait, amelyek láthatók az API-kulcshoz tartozó felhasználó számára. Egy nyilvánosan látható csoport nyilvános szavazásait olyan felhasználó is listázhatja, aki nem tagja a csoportnak; a privát szavazásokhoz továbbra is csak azok a felhasználók férhetnek hozzá, akik a Loomióban is olvashatják ő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 azokat a javaslatokat, amelyekről már döntés született.

GET /api/b2/polls

Paraméterek

Korábbi paraméterek: a per és a from a limit és az offset alternatív neveként használható, és továbbra is működik.

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 jogosultsággal kell rendelkeznie az adott szavazás szerkesztéséhez.

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

Törölj logikailag egy szavazást az API-kulcshoz tartozó felhasználóként. Ez töröltként jelöli a szavazást, de megtartja a szavazás rekordját.

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ázza az API-kulcshoz tartozó felhasználó számára látható tagságokat. A csoport tagjai láthatják a tagok nevét, azonosítóját, titulusát és szerepkörét. Az e-mail-címek csak az API-kulcshoz tartozó felhasználó saját fiókjánál szerepelnek, illetve akkor, ha ez 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 egy listát az e-mail-címekről. A művelet minden új e-mail-címre meghívót küld 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 paramétert, a csoport minden olyan tagja eltávolításra kerül, aki nem szerepel a listában. Légy óvatos, mert a csoportod összes tagját 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, amely ezt tartalmazza: {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.