Документація користувацького API Loomio

/api/b2 — користувацький API для інтеграцій із Loomio. Він використовує ключ API облікового запису користувача. Усі дії виконуються від імені цього користувача.

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

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

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

Використовуйте HTTPS-адресу призначення з URL-адресою, яку неможливо вгадати. Loomio вимагає, щоб адреса призначення вказувала на публічну IP-адресу, і блокує запити до локальних або приватних мережевих адрес.

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

Список тем

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

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