Дакументацыя 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. Выключэнні ўжываюцца да звязаных запісаў, а не да асноўнага рэсурсу, запытанага праз канцавы пункт.

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

Агляд канцавых пунктаў

Групы

Спіс груп

Вяртае групы, у якіх уліковы запіс, якому належыць ключ 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 карыстальніка працуе на аснове запытаў: інтэграцыя звяртаецца да Loomio, калі ёй трэба прачытаць або змяніць даныя. Вэбхук групы забяспечвае адпраўку даных у зваротным кірунку. Loomio адпраўляе выбраныя падзеі групы на ваш канчатковы пункт адразу, калі яны адбываюцца, таму інтэграцыі не трэба перыядычна звяртацца да REST API, каб правяраць змены.

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

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

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

Агенты і іншыя інтэграцыі могуць замест гэтага кіраваць вэбхукамі праз апісаныя ніжэй канчатковыя пункты чат-ботаў з аўтэнтыфікацыяй 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 не дадае подпіс вэбхука, загаловак з агульным сакрэтам, ідэнтыфікатар падзеі або ідэнтыфікатар дастаўкі. Стаўцеся да поўнага 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 прымяняе тыя ж правілы бачнасці груп, што і справаздача ў праграме. 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

Атрыманне апытання

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

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, або калі ўладальнікі ключа 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"]}.