Документация пользовательского 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 не добавляет подпись вебхука, заголовок с общим секретом, 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

Получить обсуждение

Получите обсуждение по числовому идентификатору или строковому ключу.

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. Темы упорядочены по времени последней активности. Идентификатор темы — её 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"]}.