Loomion käyttäjän API:n dokumentaatio

/api/b2 on Loomio-integraatioiden käyttäjäkohtainen API. Se käyttää käyttäjätilin API-avainta, ja kaikki toiminnot tehdään kyseisen käyttäjän nimissä.

Ryhmiä koskevissa toiminnoissa noudatetaan API-avaimen käyttäjän jäsenyyksiä ja ryhmäoikeuksia. Instanssin ylläpitäjän asema ei laajenna API-avaimen pääsyä ryhmiin tai sisältöön. Käytä instanssin hallintaan palvelimen API:a.

Käytä sen Loomio-käyttäjätilin API-avainta, jonka nimissä toiminnot tehdään. Erillinen bottitili on hyödyllinen, jos integraatiota ei pidä kutsua kyselyihin tai sen ei pidä saada ilmoituksia.

Kirjautuneet käyttäjät löytävät API-avaimensa ja ryhmiensä tunnukset API-käyttösivulta.

Lähetä API-avain Authorization: Bearer -otsakkeessa. Kyselymerkkijonossa lähetetyt API-avaimet hylätään, koska välityspalvelimet ja käyttölokit voivat tallentaa URL-osoitteita.

Todennuksen muutos

API-avain hyväksyttiin aiemmin URL-parametrina api_key. Pyynnöt, joissa käytetään parametria ?api_key=YOUR_API_KEY, eivät enää toimi. Käytä sen sijaan HTTP-otsaketta Authorization:

Authorization: Bearer YOUR_API_KEY

Esimerkeissä käytetään arvoja YOUR_API_KEY, ryhmätunnusta 123 ja osoitetta https://www.loomio.com/. Korvaa ne omalla API-avaimellasi, ryhmätunnuksellasi ja Loomio-asennuksesi URL-osoitteella.

Vastauksen koko ja liittyvät tietueet

Käyttäjän API:n vastaukset ovat yhdistelmämuotoisia: ensisijaisten tietueiden mukana tulee niihin liittyviä tietueita, kuten aiheita, ryhmiä, käyttäjiä, kyselyitä ja reaktioita. Näin asiakasohjelma voi täyttää paikallisen tietuevarastonsa yhdellä pyynnöllä, mutta vastaus voi sisältää enemmän tietoa kuin yksinkertainen integraatio tarvitsee.

Anna parametri compact=1, jos haluat jättää pois tilaa vievät liittyvät aiheet, ryhmät, pääryhmät, jäsenyydet, reaktiot, tunnisteet ja käännökset. Ensisijaiset tietueet ja niiden sisällön tulkintaan tarvittavat liittyvät tietueet säilyvät vastauksessa.

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

Jos haluat valita pois jätettävät tyypit itse, anna parametrille exclude_types välilyönneillä erotetut tietuetyypit yksikkömuodossa. Esimerkiksi exclude_types=group reaction jättää pois liittyvät ryhmät ja reaktiot. Tavallisia arvoja ovat topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome ja topic_item. Poisjättö koskee liittyviä tietueita, ei päätepisteestä pyydettyä ensisijaista resurssia.

Kokoelmavastauksissa on meta.total, kun kokoelman tarkka koko on määritetty. Kokonaismäärä lasketaan ennen parametrien limit ja offset käyttöä. Esimerkiksi hakupäätepiste jättää meta.total-kentän pois, kun se palauttaa tarkoituksella rajatun tulosjoukon. Se ei palauta arvoa null.

Päätepisteiden yhteenveto

Ryhmät

Listaa ryhmät

Palauta ryhmät, joissa API-avaimen käyttäjällä on aktiivinen jäsenyys.

GET /api/b2/groups

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

Vastaus sisältää kaikki ehdot täyttävät tietueet sivuttamattomassa groups-taulukossa. Mukana ovat pääryhmät ja alaryhmät, myös ryhmät, joiden tilaus ei ole tällä hetkellä voimassa. Tarkista enabled-kenttä, jos integraation pitää käsitellä vain käytössä olevia ryhmiä.

Tärkeitä ryhmän kenttiä ovat:

Vastaus voi sisältää myös muita ryhmäasetuksia, liittyviä pääryhmän tietueita ja API-käyttäjän jäsenyyksiä. Asiakasohjelman tulee ohittaa kentät, joita se ei käytä.

Hae ryhmä

Palauta yksi API-avaimen käyttäjälle näkyvä ryhmä.

GET /api/b2/groups/:id_or_key_or_handle

Tunnisteena voi käyttää ryhmän numeerista tunnusta, lyhyttä tunnusta tai ryhmätunnistetta.

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

Vastaus sisältää ryhmän groups-taulukossa ja käyttää samoja kenttiä kuin listauspäätepiste. Jos API-avaimen käyttäjällä ei ole pääsyä pyydettyyn ryhmään, palvelin palauttaa oikeusvirheen.

Webhookit

Käyttäjän API perustuu pyyntöihin: integraatio kutsuu Loomiota, kun se haluaa lukea tai muuttaa tietoja. Ryhmän webhook lähettää tietoa toiseen suuntaan. Loomio lähettää valitut ryhmän tapahtumat päätepisteeseesi niiden tapahtuessa, joten integraation ei tarvitse kysellä muutoksia REST API:sta.

Webhookit määritetään ryhmäkohtaisesti, ja niiden hallintaan tarvitaan ryhmän ylläpitäjän oikeudet. Voit hallita niitä Loomion käyttöliittymässä:

1. Avaa ryhmä.
2. Avaa ryhmän valikko ja valitse Chat-integraatiot.
3. Lisää integraatio, jonka sisältömuoto sopii päätepisteellesi. Yleiskäyttöiselle päätepisteelle sopii Mattermost/Markdown-muoto.
4. Anna nimi ja kohteen URL-osoite.
5. Valitse tapahtumat, jotka Loomion pitää lähettää automaattisesti.
6. Tallenna integraatio ja lähetä testiviesti valitsemalla Testaa yhteys.

Käytä HTTPS-kohdetta, jonka URL-osoitetta ei voi arvata. Loomio edellyttää, että kohdeosoite vastaa julkista osoitetta, ja estää pyynnöt paikallisiin tai yksityisiin verkko-osoitteisiin.

Agentit ja muut integraatiot voivat hallita webhookeja myös alla kuvattujen Bearer-todennettujen chatbot-päätepisteiden kautta. Resurssin nimi on chatbots, jotta se on yhteensopiva Loomion chat-integraatioiden kanssa. Se kattaa myös yleiset lähtevät webhookit.

Listaa webhookit

Palauta ryhmälle määritetyt chat-integraatiot. API-avaimen käyttäjän on oltava kyseisen ryhmän ylläpitäjä. Vastaus sisältää kohteiden URL-osoitteet, joten sitä ei saa näyttää tavallisille ryhmän jäsenille.

GET /api/b2/chatbots?group_id=123

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

Vastaus sisältää chatbots-taulukon, jossa on seuraavat kentät:

Luo webhook

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

API-avaimen käyttäjän on oltava group_id-ryhmän ylläpitäjä. Ennen tallennusta tarkistetaan, että kohteen URL-osoite on julkinen.

Päivitä webhook

PATCH /api/b2/chatbots/:id

Lähetä kentät, joita haluat muuttaa. Webhookia ei voi siirtää toiseen ryhmään muuttamalla group_id-kenttää.

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

Testaa webhookin kohde

Lähetä kohteeseen Markdown-muotoinen testiviesti ennen asetusten tallentamista tai sen jälkeen.

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

Poista webhook

DELETE /api/b2/chatbots/:id

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

Asetusten poistaminen lopettaa tulevat lähetykset. Se ei poista ryhmän sisältöä Loomiosta.

Tapahtumatyypit

Webhook voi tilata seuraavat tapahtumatyypit:

Webhook kuuluu yhteen ryhmään ja vastaanottaa ryhmästä tilaamansa tapahtumat. Käyttäjät voivat myös valita integraation erikseen jakaessaan sisältöä tai lähettäessään joitakin ilmoituksia, vaikka vastaavaa automaattista tapahtumaa ei olisi valittu.

HTTP-lähetys

Loomio lähettää määritettyyn URL-osoitteeseen asynkronisen HTTP POST -pyynnön, jossa on seuraava otsake:

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

Pyynnön aikakatkaisu on viisi sekuntia. 2xx-vastaus, myös 204 No Content, tulkitaan onnistumiseksi. Webhookin vastaanottajan kannattaa vastata nopeasti, käsitellä pidemmät tehtävät asynkronisesti ja varautua päällekkäisiin tai väärässä järjestyksessä saapuviin lähetyksiin.

Loomio ei tällä hetkellä lisää webhookin allekirjoitusta, jaetun salaisuuden otsaketta, tapahtumatunnusta eikä lähetystunnusta. Käsittele koko kohteen URL-osoitetta tunnistetietona äläkä julkaise sitä. Lisää URL-osoitteeseen vaikeasti arvattava tunniste, jos vastaanottava palvelu tukee sitä. Jos tarvitset vakaan, koneellisesti luettavan tapahtumamallin tai allekirjoitetun lähetyksen, käytä webhookia muutosilmoituksena ja hae ajantasaiset tietueet tunnistautumista edellyttävän käyttäjän API:n kautta.

Viestien muodot

Webhookin viestit on tarkoitettu näytettäviksi chat-palveluissa. Ne eivät sisällä täydellisiä Loomio-tietueita. Viestin linkit osoittavat sisältöön, jota tapahtuma koskee. Integraatio voi hakea ajantasaiset rakenteiset tiedot käyttäjän API:n kautta.

Esimerkiksi yleisen Markdown-muodon viestin runko on seuraavanlainen:

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

Viestin tarkka teksti riippuu tapahtumasta, ryhmän kieliasetuksesta, pelkän ilmoituksen asetuksesta ja Loomion versiosta. Vastaanottajan kannattaa käyttää valitun muodon dokumentoituja ylimmän tason kenttiä sen sijaan, että se tulkitsisi lauseiden sanamuotoa.

Haku

Hae keskusteluja, kommentteja, kyselyitä, ääniä ja johtopäätöksiä, jotka API-avaimen käyttäjä voi nähdä. Tuloksiin sisältyy julkista sisältöä, vaikka käyttäjä ei olisi ryhmän jäsen. Yksityisen sisällön näkyvyys määräytyy aiheen tavallisten käyttöoikeuksien mukaan.

GET /api/b2/search

Parametrit

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

Vastaus sisältää search_results-taulukon. Jokainen tulos yksilöi löytyneen tietueen ja sen näkyvän asiayhteyden. Kenttiä ovat esimerkiksi searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at ja tags. Kentän arvo on null, jos kenttä ei koske tulosta.

Osallistumisraportti

Palauta samat koostetut osallistumistiedot, joita Loomion osallistumisraportti käyttää.

GET /api/b2/reports

Parametrit

Henkilö on delegaatti, jos hänellä on aktiivinen delegaatin jäsenyys jossakin valitussa ryhmässä. Hänen lukumääränsä lasketaan yhteen kaikista valituista ryhmistä. Delegaatin rivi palautetaan, vaikka kaikki toiminnan lukumäärät olisivat nollia. Lukumäärät kattavat ketjut, kommentit, kyselyt, äänet, johtopäätökset ja reaktiot. Ne eivät kuvaa äänestysaktiivisuutta. Käyttäjän riveillä näkyvät myös tunnistettujen äänestyslippujen määrät: lähetetyt, annetut ja käyttämättä jääneet. Nimettömät kyselyt eivät sisälly henkilökohtaisiin äänimääriin. all_votes_cast on tosi vain, jos vähintään yksi äänestyslippu on lähetetty ja kaikki lähetetyt äänestysliput on käytetty.

API noudattaa samoja ryhmän näkyvyyssääntöjä kuin Loomion oma raportti. Käyttäjän API-avain ei voi paljastaa raporttitietoja ryhmistä, joihin käyttäjällä ei ole pääsyä.

Esimerkki

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'

users-taulukko sisältää täydet toimintatiedot kullakin rivillä:

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

Luo keskustelu

Luo keskustelu API-avaimen käyttäjänä.

POST /api/b2/discussions

Parametrit

Esimerkki

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

Hae keskustelu

Hae keskustelu sen numeerisella tunnuksella tai merkkijonomuotoisella avaimella.

GET /api/b2/discussions/:id

Esimerkki

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

Listaa keskustelut

Listaa ryhmän keskustelut, jotka API-avaimen käyttäjä näkee. Julkisesti näkyvän ryhmän julkiset keskustelut voi listata myös henkilö, joka ei kuulu ryhmään. Yksityiset keskustelut näkyvät vain käyttäjille, joilla on niihin lukuoikeus Loomiossa.

GET /api/b2/discussions

Parametrit

Vanhat parametrit per ja from toimivat edelleen parametrien limit ja offset vaihtoehtoisina niminä.

Esimerkki

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

Listaa keskusteluketjut

Listaa API-avaimen käyttäjälle näkyvät keskustelu- ja kyselyketjut viimeisimmän toiminnan mukaan järjestettyinä. Keskusteluketjun tunnus on sen topic_id.

GET /api/b2/threads

Parametrit

Esimerkki

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

Lue keskusteluketju

Lue keskusteluketju, sen aikajärjestyksessä olevat tapahtumat tai koko näkyvä Markdown-asiakirja.

GET /api/b2/threads/:topic_id

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

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

Esimerkki

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

items-rajapinta palauttaa tapahtumat järjestyksessä, mukaan lukien näkyvät kommentit, kyselyt, äänet ja johtopäätökset. markdown-rajapinta palauttaa koko näkyvän keskusteluketjun yhtenä Markdown-asiakirjana. Äänten perustelut sisältyvät vastaukseen vain, jos API-avaimen käyttäjä saa nähdä ne.

Kaikki keskusteluketjujen rajapinnat noudattavat samoja käyttöoikeuksia kuin Loomion käyttöliittymä. API-avain ei anna pääsyä keskusteluketjuun, jota käyttäjä ei normaalisti voi avata.

Muokkaa keskustelua

Muokkaa keskustelua API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä keskustelua.

PATCH /api/b2/discussions/:id

Parametrit

Esimerkki

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

Poista keskustelu pehmeästi

Poista keskustelu pehmeästi API-avaimen käyttäjänä. Keskustelu poistuu käytöstä, mutta sen tietue säilyy.

DELETE /api/b2/discussions/:id

Esimerkki

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

Luo kommentti

Luo kommentti keskusteluun API-avaimen käyttäjänä.

POST /api/b2/comments

Parametrit

Esimerkki

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

Muokkaa kommenttia

Muokkaa kommenttia API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä kommenttia.

PATCH /api/b2/comments/:id

Parametrit

Esimerkki

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

Poista kommentti pehmeästi

Poista kommentti pehmeästi API-avaimen käyttäjänä. Kommentti poistuu käytöstä ja sen teksti piilotetaan, mutta kommentin tietue säilyy.

DELETE /api/b2/comments/:id

Esimerkki

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

Luo kysely

Luo kysely API-avaimen käyttäjänä.

POST /api/b2/polls

Parametrit

Esimerkki

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

Näytä kysely

Hae kysely sen numeerisella tunnuksella tai merkkijonomuotoisella avaimella.

GET /api/b2/polls/:id

Esimerkki

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

Listaa kyselyt

Listaa ryhmän kyselyt, jotka näkyvät API-avaimen käyttäjälle. Julkisesti näkyvän ryhmän julkiset kyselyt voi listata myös henkilö, joka ei kuulu ryhmään. Yksityiset kyselyt näkyvät vain käyttäjille, joilla on oikeus lukea niitä Loomiossa. Vastaus sisältää kunkin näkyvän kyselyn nykyisen lopputuloksen, joten voit käyttää arvoa status=closed päätettyjen ehdotusten listaamiseen.

GET /api/b2/polls

Parametrit

Vanhat parametrit per ja from toimivat edelleen parametrien limit ja offset vaihtoehtoisina niminä.

Esimerkki

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

Muokkaa kyselyä

Muokkaa kyselyä API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä kyselyä.

PATCH /api/b2/polls/:id

Parametrit

Esimerkki

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

Poista kysely pehmeästi

Poista kysely pehmeästi API-avaimen käyttäjänä. Kysely poistuu käytöstä, mutta sen tietue säilyy.

DELETE /api/b2/polls/:id

Esimerkki

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

Listaa jäsenyydet

Listaa jäsenyydet, jotka näkyvät API-avaimen käyttäjälle. Ryhmän jäsenet voivat nähdä jäsenten nimet, tunnukset, tittelit ja roolit. Sähköpostiosoitteet näkyvät vain API-avaimen käyttäjän omalta tililtä tai silloin, kun API-avaimen käyttäjä on ryhmän ylläpitäjä.

GET /api/b2/memberships

Parametrit

Esimerkki

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

Hallinnoi jäsenyyksiä

Lähetä luettelo sähköpostiosoitteista. Uudet osoitteet kutsutaan ryhmään. Toisin kuin jäsenyyksien listaaminen, tämä toiminto edellyttää ryhmän ylläpitäjän oikeuksia.

POST /api/b2/memberships

Parametrit

Esimerkki

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

Jos annat arvon remove_absent=1, kaikki ryhmän jäsenet, joita ei ole luettelossa, poistetaan ryhmästä. Ole varovainen: voit poistaa ryhmästäsi kaikki jäsenet.

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

Vastaus on olio, jossa on {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.