Дакументацыя API карыстальніка Loomio

/api/b2 — API для інтэграцый з Loomio, якія дзейнічаюць ад імя карыстальніка. Ён выкарыстоўвае ключ API ўліковага запісу, і кожнае дзеянне выконваецца ад імя гэтага карыстальніка.

Аперацыі з групамі залежаць ад удзелу ў групах і правоў карыстальніка, якому належыць ключ API. Правы адміністратара сервера не пашыраюць доступ ключа API да груп або іх змесціва. Для адміністравання сервера выкарыстоўвайце API сервера.

Выкарыстоўвайце ключ API ўліковага запісу Loomio, ад імя якога будуць выконвацца дзеянні. Асобны ўліковы запіс бота падыходзіць для інтэграцыі, якой не трэба атрымліваць запрашэнні да апытанняў або апавяшчэнні.

Карыстальнікі, якія ўвайшлі ў сістэму, могуць знайсці свой ключ API і ідэнтыфікатары груп на старонцы доступу да API.

Перадавайце ключ API ў загалоўку Authorization: Bearer. Ключы API ў радку запыту адхіляюцца, бо URL-адрасы могуць захоўвацца ў журналах проксі-сервераў і доступу.

Змена спосабу аўтэнтыфікацыі

Раней ключ API можна было перадаваць у параметры URL-адраса api_key. Запыты з ?api_key=YOUR_API_KEY больш не працуюць. Замест гэтага выкарыстоўвайце HTTP-загаловак Authorization:

Authorization: Bearer YOUR_API_KEY

У прыкладах выкарыстоўваюцца YOUR_API_KEY, ідэнтыфікатар групы 123 і https://www.loomio.com/. Замяніце іх сваім ключом API, ідэнтыфікатарам групы і URL-адрасам вашага сервера Loomio.

Памер адказу і звязаныя запісы

Адказы API карыстальніка маюць складаны фармат: разам з асноўнымі запісамі вяртаюцца звязаныя запісы, напрыклад тэмы, групы, карыстальнікі, апытанні і рэакцыі. Гэта дазваляе кліенту запоўніць лакальнае сховішча запісаў адным запытам, але аб'ём даных можа быць большым, чым патрэбна простай інтэграцыі.

Перадайце compact=1, каб выключыць аб'ёмныя звязаныя запісы тэм, груп, бацькоўскіх груп, удзелу ў групах, рэакцый, тэгаў і перакладаў. Асноўныя запісы і звязаныя запісы, неабходныя для разумення іх змесціва, застануцца ў адказе.

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

Для дакладнейшага кіравання перадайце exclude_types з тыпамі запісаў у адзіночным ліку, падзеленымі прабеламі. Напрыклад, exclude_types=group reaction выключае звязаныя групы і рэакцыі. Распаўсюджаныя значэнні: topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome і topic_item. Выключэнні тычацца звязаных запісаў, а не асноўнага рэсурсу, запытанага праз гэты адрас API.

Адказы з калекцыямі ўтрымліваюць meta.total, калі можна вызначыць дакладны памер калекцыі. Агульная колькасць вылічаецца да прымянення limit і offset. Адрасы API, якія наўмысна вяртаюць абмежаваны набор вынікаў, напрыклад пошук, не ўключаюць meta.total замест вяртання null.

Агляд адрасоў API

Групы

Спіс груп

Вяртае групы, у якіх карыстальнік, якому належыць ключ API, мае актыўны ўдзел.

GET /api/b2/groups

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

Адказ утрымлівае ўсе адпаведныя запісы ў масіве groups без падзелу на старонкі. Ён уключае бацькоўскія групы і падгрупы, у тым ліку групы, падпіска якіх цяпер неактыўная. Правярайце поле enabled, калі інтэграцыя павінна працаваць толькі з актыўнымі групамі.

Асноўныя палі групы:

Адказ можа таксама ўтрымліваць дадатковыя налады групы, звязаныя запісы бацькоўскай групы і звесткі пра ўдзел карыстальніка API ў групах. Кліенты павінны ігнараваць палі, якія ім не патрэбныя.

Атрымаць групу

Вяртае адну групу, даступную карыстальніку, якому належыць ключ API.

GET /api/b2/groups/:id_or_key_or_handle

Ідэнтыфікатарам можа быць лічбавы ID групы, яе ключ або кароткая назва.

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

Адказ утрымлівае групу ў масіве groups з тымі ж палямі, што і адрас API для спісу груп. Запыт групы, да якой карыстальнік з ключом API не мае доступу, вяртае памылку правоў доступу.

Вэбхукі

API карыстальніка працуе праз запыты: інтэграцыя звяртаецца да Loomio, калі хоча прачытаць або змяніць даныя. Вэбхук групы перадае даныя ў адваротным кірунку. Loomio адпраўляе выбраныя падзеі групы на ваш адрас API адразу пасля іх узнікнення, таму інтэграцыі не трэба рэгулярна апытваць REST API пра змены.

Вэбхукі наладжваюцца асобна для кожнай групы. Для гэтага патрэбныя правы адміністратара групы. Кіраваць імі можна праз інтэрфейс Loomio:

1. Адкрыйце групу.
2. Адкрыйце меню групы і выберыце Інтэграцыі з чатам.
3. Дадайце інтэграцыю з фарматам даных, які прымае ваш адрас API. Для адраса агульнага прызначэння выкарыстоўвайце фармат Mattermost/Markdown.
4. Увядзіце назву і URL-адрас атрымальніка.
5. Выберыце падзеі, якія Loomio павінен адпраўляць аўтаматычна.
6. Захавайце інтэграцыю і націсніце Тэставае падключэнне, каб адправіць тэставае паведамленне.

Выкарыстоўвайце HTTPS-адрас атрымальніка, які немагчыма адгадаць. Loomio патрабуе, каб адрас вёў да публічнага IP-адраса, і блакуе запыты да лакальных або прыватных сеткавых адрасоў.

Агенты і іншыя інтэграцыі могуць кіраваць вэбхукамі праз апісаныя ніжэй адрасы API чат-ботаў з аўтэнтыфікацыяй Bearer. Рэсурс называецца chatbots дзеля сумяшчальнасці з інтэграцыямі Loomio з чатам, але ён таксама прадстаўляе звычайныя выходныя вэбхукі.

Спіс вэбхукаў

Вяртае інтэграцыі з чатам, наладжаныя для групы. Карыстальнік, якому належыць ключ API, павінен быць адміністратарам гэтай групы. Адказ утрымлівае URL-адрасы атрымальнікаў, таму яго нельга паказваць звычайным удзельнікам групы.

GET /api/b2/chatbots?group_id=123

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

Адказ утрымлівае масіў chatbots з наступнымі палямі:

Стварыць вэбхук

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, патрэбныя правы адміністратара групы group_id. Перад захаваннем правяраецца, ці вядзе URL атрымальніка на агульнадаступны адрас.

Абнавіць вэбхук

PATCH /api/b2/chatbots/:id

Перадайце палі, якія трэба змяніць. Змяніць групу вэбхука праз поле group_id нельга.

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

Праверыць адрас вэбхука

Адпраўце на адрас тэставае паведамленне ў фармаце, сумяшчальным з Markdown. Гэта можна зрабіць да або пасля захавання канфігурацыі.

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

Выдаліць вэбхук

DELETE /api/b2/chatbots/:id

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

Пасля выдалення канфігурацыі новыя паведамленні больш не адпраўляюцца. Змесціва групы ў Loomio не выдаляецца.

Тыпы падзей

Вэбхук можа атрымліваць паведамленні пра наступныя тыпы падзей:

Вэбхук належыць адной групе і атрымлівае паведамленні пра выбраныя падзеі гэтай групы. Людзі таксама могуць самі выбраць інтэграцыю, калі дзеляцца змесцівам або адпраўляюць некаторыя апавяшчэнні, нават калі адпаведная аўтаматычная падзея не выбрана.

Дастаўка праз HTTP

Loomio асінхронна адпраўляе HTTP-запыт POST на зададзены URL з наступным загалоўкам:

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

Час чакання адказу складае пяць секунд. Любы адказ 2xx, у тым ліку 204 No Content, лічыцца паспяховым. Сэрвісам, якія прымаюць вэбхукі, варта адказваць хутка, выконваць працяглую апрацоўку асінхронна і ўлічваць магчымасць паўторнай дастаўкі або дастаўкі не ў парадку адпраўкі.

Цяпер Loomio не дадае подпіс вэбхука, загаловак з агульным сакрэтам, ID падзеі або ID дастаўкі. Лічыце поўны URL атрымальніка ўліковымі данымі і не публікуйце яго. Калі сэрвіс-атрымальнік падтрымлівае гэта, уключыце ў URL токен, які немагчыма адгадаць. Калі патрэбная стабільная схема падзей для машыннай апрацоўкі або дастаўка з подпісам, выкарыстоўвайце вэбхук як апавяшчэнне пра змену, а актуальныя запісы атрымлівайце праз API карыстальніка з аўтэнтыфікацыяй.

Фарматы даных

Даныя вэбхукаў — гэта паведамленні для чат-сэрвісаў, а не поўныя серыялізаваныя запісы Loomio. Спасылкі ў паведамленні паказваюць на адпаведнае змесціва ў Loomio. Калі інтэграцыі патрэбныя структураваныя актуальныя даныя, яна можа атрымаць іх праз API карыстальніка.

Напрыклад, паведамленне ў агульным фармаце Markdown мае такую структуру:

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

Дакладны тэкст паведамлення залежыць ад падзеі, мовы групы, налады адпраўкі толькі загалоўка апавяшчэння і версіі Loomio. Пры апрацоўцы абапірайцеся на задакументаваныя палі верхняга ўзроўню выбранага фармату, а не на фармулёўкі сказаў.

Пошук

Шукайце абмеркаванні, каментарыі, апытанні, галасы і высновы, даступныя карыстальніку з ключом API. Вынікі ўключаюць агульнадаступнае змесціва, нават калі гэты карыстальнік не ўваходзіць у адпаведную групу. Доступ да прыватнага змесціва вызначаецца звычайнымі правіламі бачнасці тэм.

GET /api/b2/search

Параметры

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

Адказ змяшчае масіў search_results. Кожны вынік вызначае знойдзены запіс і яго даступны кантэкст праз палі, у тым ліку searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at і tags. Палі, якія не датычацца выніку, маюць значэнне null.

Справаздача аб удзеле

Вяртае зводныя даныя аб удзеле, якія выкарыстоўваюцца ў справаздачы Loomio аб удзеле.

GET /api/b2/reports

Параметры

Статус дэлегата маюць людзі з актыўным членствам у якасці дэлегата ў любой з выбраных груп. Іх паказчыкі сумуюцца па ўсіх выбраных групах. Радкі дэлегатаў вяртаюцца, нават калі ўсе паказчыкі актыўнасці роўныя нулю. Падлічваюцца тэмы, каментарыі, апытанні, галасы, высновы і рэакцыі; гэтыя паказчыкі не з'яўляюцца доляй удзелу ў галасаваннях. Радкі карыстальнікаў таксама ўключаюць колькасць выдадзеных бюлетэняў для паіменнага галасавання, пададзеных галасоў і бюлетэняў без пададзенага голасу. Ананімныя апытанні не ўключаюцца ў паказчыкі галасавання асобных людзей. all_votes_cast мае значэнне true, толькі калі быў выдадзены хаця б адзін бюлетэнь і па кожным выдадзеным бюлетэні быў пададзены голас.

API прымяняе тыя ж правілы бачнасці груп, што і справаздача ў Loomio. Ключ API карыстальніка не дае доступу да даных справаздачы па групах, да якіх гэты карыстальнік не мае доступу.

Прыклад

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 змяшчае поўныя радкі з данымі аб актыўнасці:

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

Стварыць абмеркаванне

Стварыце абмеркаванне ад імя карыстальніка, якому належыць ключ API.

POST /api/b2/discussions

Параметры

Прыклад

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

Атрымаць абмеркаванне

Атрымайце абмеркаванне па яго лікавым ID або тэкставым ключы.

GET /api/b2/discussions/:id

Прыклад

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

Спіс абмеркаванняў

Атрымайце спіс абмеркаванняў у групе, даступных карыстальніку, якому належыць ключ API. У публічнай групе людзі, якія не ўваходзяць у яе, могуць атрымаць спіс публічных абмеркаванняў. Прыватныя абмеркаванні даступныя толькі тым, хто можа чытаць іх у Loomio.

GET /api/b2/discussions

Параметры

Для сумяшчальнасці per і from прымаюцца як альтэрнатыўныя назвы для limit і offset і будуць працаваць надалей.

Прыклад

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

Спіс тэм

Атрымайце спіс тэм абмеркаванняў і апытанняў, даступных карыстальніку, якому належыць ключ API. Тэмы ўпарадкаваны паводле апошняй актыўнасці. ID тэмы — гэта яе topic_id.

GET /api/b2/threads

Параметры

Прыклад

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

Прачытаць тэму

Прачытайце тэму, упарадкаваны паток яе падзей або поўны даступны дакумент у фармаце Markdown.

GET /api/b2/threads/:topic_id

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

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

Прыклад

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 вяртае ўпарадкаваны паток падзей, у тым ліку даступныя каментары, апытанні, галасы і высновы. Канчатковы пункт markdown вяртае ўсю даступную тэму як адзін дакумент Markdown. Прычыны галасавання ўключаюцца толькі тады, калі яны даступныя карыстальніку, якому належыць ключ API.

Для ўсіх канчатковых пунктаў тэм дзейнічаюць тыя ж правы доступу, што і ў інтэрфейсе Loomio. Ключ API не дае доступу да тэмы, якую карыстальнік звычайна не можа адкрыць.

Рэдагаваць абмеркаванне

Адрэдагуйце абмеркаванне ад імя карыстальніка, якому належыць ключ API. Дзейнічаюць тыя ж правы, што і ў Loomio: гэты карыстальнік павінен мець права рэдагаваць абмеркаванне.

PATCH /api/b2/discussions/:id

Параметры

Прыклад

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

Мякка выдаліць абмеркаванне

Мякка выдаліце абмеркаванне ад імя карыстальніка, якому належыць ключ API. Абмеркаванне будзе пазначана як выдаленае, але яго запіс застанецца.

DELETE /api/b2/discussions/:id

Прыклад

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

Стварыць каментар

Стварыце каментар у абмеркаванні ад імя карыстальніка, якому належыць ключ API.

POST /api/b2/comments

Параметры

Прыклад

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

Рэдагаваць каментар

Адрэдагуйце каментар ад імя карыстальніка, якому належыць ключ API. Дзейнічаюць тыя ж правы, што і ў Loomio: гэты карыстальнік павінен мець права рэдагаваць каментар.

PATCH /api/b2/comments/:id

Параметры

Прыклад

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

Мякка выдаліць каментар

Мякка выдаліце каментар ад імя карыстальніка, якому належыць ключ API. Тэкст каментара будзе схаваны, але яго запіс застанецца.

DELETE /api/b2/comments/:id

Прыклад

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

Стварыць апытанне

Стварыце апытанне ад імя карыстальніка, якому належыць ключ API.

POST /api/b2/polls

Параметры

Прыклад

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

Атрымаць апытанне

Атрымайце апытанне па яго лікавым ідэнтыфікатары або радковым ключы.

GET /api/b2/polls/:id

Прыклад

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

Спіс апытанняў

Атрымайце спіс апытанняў групы, бачных карыстальніку, якому належыць ключ API. У агульнадаступнай групе людзі, якія не ўваходзяць у яе, могуць атрымаць спіс агульнадаступных апытанняў. Прыватныя апытанні даступныя толькі тым, хто можа праглядаць іх у Loomio. Адказ змяшчае бягучую выснову для кожнага бачнага апытання, таму праз status=closed можна атрымаць спіс прапаноў з прынятай высновай.

GET /api/b2/polls

Параметры

Для сумяшчальнасці per і from прымаюцца як альтэрнатыўныя назвы для limit і offset і будуць працаваць надалей.

Прыклад

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

Рэдагаваць апытанне

Рэдагуйце апытанне ад імя карыстальніка, якому належыць ключ API. Дзейнічаюць тыя ж правы, што і ў Loomio: карыстальніку павінна быць дазволена рэдагаваць гэтае апытанне.

PATCH /api/b2/polls/:id

Параметры

Прыклад

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

Мякка выдаліць апытанне

Мякка выдаліце апытанне ад імя карыстальніка, якому належыць ключ API. Апытанне будзе адхілена, але запіс пра яго застанецца.

DELETE /api/b2/polls/:id

Прыклад

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

Спіс удзельнікаў групы

Атрымайце спіс удзельнікаў груп, бачных карыстальніку, якому належыць ключ API. Удзельнікі групы могуць бачыць імёны, ідэнтыфікатары, пасады і ролі іншых удзельнікаў. Адрасы электроннай пошты даступныя толькі для ўласнага ўліковага запісу карыстальніка, якому належыць ключ API, або калі гэты карыстальнік мае правы адміністратара групы.

GET /api/b2/memberships

Параметры

Прыклад

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

Кіраванне ўдзельнікамі групы

Адпраўце спіс адрасоў электроннай пошты. На ўсе новыя адрасы будуць адпраўлены запрашэнні ў групу. У адрозненне ад прагляду спіса ўдзельнікаў, для гэтай аперацыі патрэбныя правы адміністратара групы.

POST /api/b2/memberships

Параметры

Прыклад

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

Калі перадаць remove_absent=1, з групы будуць выдалены ўсе ўдзельнікі, не ўключаныя ў спіс. Будзьце ўважлівыя: так можна выдаліць з вашай групы ўсіх удзельнікаў.

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

У адказ вяртаецца аб’ект {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.