Документация пользовательского API Loomio

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

Операции с группами учитывают участие в группах и права в них пользователя, которому принадлежит API-ключ. Статус администратора экземпляра Loomio не расширяет доступ 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 назначения как с учётными данными, не публикуйте его и включайте в 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"]}.