Документація користувацького 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

Ідентифікатором може бути числовий ідентифікатор, ключ або псевдонім групи.

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-адреси призначення як до облікових даних, не оприлюднюйте її та додайте до неї токен, який неможливо вгадати, якщо сервіс-отримувач це підтримує. Якщо потрібна стабільна машиночитана схема подій або підписана доставка, використовуйте вебхук як сповіщення про зміни й отримуйте актуальні записи через Користувацький 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 або якщо цей користувач є адміністратором групи.

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