Documentação da API do usuário do Loomio

/api/b2 é a API voltada a usuários para integrações com o Loomio. Ela usa a chave de API de uma conta de usuário, e todas as ações são realizadas em nome desse usuário.

As operações em grupos seguem as participações e permissões de grupo do usuário da chave de API. Ser administrador da instância não amplia o acesso da chave de API a grupos ou conteúdos. Para administrar a instância, use a API do servidor.

Use a chave de API da conta do Loomio que realizará as ações. Uma conta exclusiva para o bot é útil quando a integração não deve ser convidada para enquetes nem receber notificações.

Após entrar no Loomio, você encontra sua chave de API e os IDs dos grupos na página de acesso à API.

Envie a chave de API no cabeçalho Authorization: Bearer. Chaves de API em parâmetros de consulta são rejeitadas porque proxies e registros de acesso podem armazenar URLs.

Alteração na autenticação

Antes, a chave de API era aceita no parâmetro de URL api_key. As solicitações com ?api_key=YOUR_API_KEY não funcionam mais. Use o cabeçalho HTTP Authorization:

Authorization: Bearer YOUR_API_KEY

Os exemplos usam YOUR_API_KEY, o ID de grupo 123 e https://www.loomio.com/. Substitua esses valores pela sua chave de API, pelo ID do grupo e pela URL da sua instalação do Loomio.

Tamanho das respostas e registros relacionados

As respostas da API do usuário têm um formato composto: os registros principais vêm acompanhados de registros relacionados, como tópicos, grupos, usuários, enquetes e reações. Assim, um cliente pode preencher seu armazenamento local de registros com uma única solicitação, embora a resposta possa conter mais dados do que uma integração simples precisa.

Passe compact=1 para omitir registros relacionados volumosos de tópicos, grupos, grupos superiores, participações, reações, etiquetas e traduções. Os registros principais e os registros relacionados necessários para interpretar seu conteúdo continuam presentes.

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads/123/items?compact=1'

Para controlar as exclusões diretamente, passe exclude_types com tipos de registro no singular separados por espaços. Por exemplo, exclude_types=group reaction omite grupos e reações relacionados. Valores comuns são topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome e topic_item. As exclusões afetam os registros relacionados, não o recurso principal solicitado ao endpoint.

As respostas de coleções incluem meta.total quando é possível determinar o tamanho exato da coleção. O total é calculado antes da aplicação de limit e offset. Endpoints como o de busca, que retornam intencionalmente um conjunto limitado de resultados, omitem meta.total em vez de retornar null.

Resumo dos endpoints

Grupos

Listar grupos

Retorna os grupos dos quais o usuário da chave de API é membro ativo.

GET /api/b2/groups

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups

A resposta contém todos os registros correspondentes em um array groups sem paginação. Ela inclui grupos superiores e subgrupos, mesmo quando a assinatura de um grupo não está ativa. Consulte o campo enabled se a integração deve operar apenas em grupos ativos.

Os principais campos de grupo são:

A resposta pode incluir outras configurações do grupo, registros relacionados do grupo superior e as participações do usuário da API. Os clientes devem ignorar os campos que não usam.

Obter um grupo

Retorna um grupo visível para o usuário da chave de API.

GET /api/b2/groups/:id_or_key_or_handle

O identificador pode ser o ID numérico, a chave ou o identificador legível do grupo.

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

A resposta contém o grupo no array groups e usa os mesmos campos do endpoint de listagem. Uma solicitação para um grupo ao qual o usuário da chave de API não tem acesso retorna um erro de permissão.

Webhooks

A API do usuário funciona por solicitação: uma integração chama o Loomio quando precisa ler ou alterar dados. Um webhook de grupo permite o envio no sentido inverso. O Loomio envia os eventos selecionados do grupo ao seu endpoint conforme acontecem, dispensando consultas periódicas à API REST para detectar mudanças.

Os webhooks são configurados por grupo e exigem permissão de administrador do grupo. Você pode gerenciá-los pela interface do Loomio:

1. Abra o grupo.
2. Abra o menu do grupo e selecione Integrações de bate-papo.
3. Adicione a integração correspondente ao formato de dados aceito pelo seu endpoint. Para um endpoint de uso geral, use o formato Mattermost/Markdown.
4. Insira um nome e a URL de destino.
5. Selecione os eventos que o Loomio deve enviar automaticamente.
6. Salve a integração e use Conexão de teste para enviar uma mensagem de teste.

Use um destino HTTPS com uma URL difícil de adivinhar. O Loomio exige que o destino corresponda a um endereço público e bloqueia solicitações a endereços de redes locais ou privadas.

Agentes e outras integrações também podem gerenciar webhooks pelos endpoints de chatbot autenticados com Bearer descritos abaixo. O recurso se chama chatbots por compatibilidade com as integrações de bate-papo do Loomio, mas também representa webhooks de saída em geral.

Listar webhooks

Retorna as integrações de bate-papo configuradas para um grupo. O usuário da chave de API precisa ser administrador desse grupo. A resposta inclui URLs de destino e, portanto, não deve ser exposta a membros comuns do grupo.

GET /api/b2/chatbots?group_id=123

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/chatbots?group_id=123'

A resposta contém um array chatbots com estes campos:

Criar um webhook

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

O usuário da chave de API precisa ser administrador de group_id. A URL de destino é validada como pública antes de ser salva.

Atualizar um webhook

PATCH /api/b2/chatbots/:id

Envie os campos que você deseja alterar. Alterar group_id não transfere o webhook para outro grupo.

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

Testar o destino de um webhook

Envie uma mensagem de teste compatível com Markdown para o destino antes ou depois de salvar a configuração.

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

Excluir um webhook

DELETE /api/b2/chatbots/:id

curl -X DELETE -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/chatbots/456

Excluir a configuração interrompe os envios futuros. O conteúdo do grupo no Loomio não é excluído.

Tipos de evento

Um webhook pode receber estes tipos de evento:

O webhook pertence a um grupo e recebe os eventos selecionados desse grupo. As pessoas também podem selecionar a integração ao compartilhar conteúdo ou enviar algumas notificações, mesmo que o evento automático correspondente não tenha sido selecionado.

Envio por HTTP

O Loomio envia uma requisição HTTP POST assíncrona para a URL configurada com este cabeçalho:

Content-Type: application/json; charset=utf-8

O tempo limite da requisição é de cinco segundos. Uma resposta 2xx, incluindo 204 No Content, é considerada bem-sucedida. O serviço que recebe o webhook deve responder rapidamente, processar tarefas demoradas de forma assíncrona e aceitar envios duplicados ou fora de ordem.

Atualmente, o Loomio não adiciona assinatura ao webhook, cabeçalho com segredo compartilhado, ID de evento nem ID de envio. Trate a URL de destino completa como uma credencial, não a divulgue publicamente e inclua um token difícil de adivinhar na URL quando o serviço receptor permitir. Se você precisar de um esquema de eventos estável e legível por máquina ou de envios assinados, use o webhook como aviso de mudança e consulte os registros atuais pela API do usuário autenticada.

Formatos dos dados enviados

Os dados enviados pelos webhooks são mensagens para exibição em serviços de bate-papo. Eles não contêm registros completos do Loomio. Os links na mensagem identificam o conteúdo afetado. Se uma integração precisar dos dados atuais em formato estruturado, ela pode consultá-los pela API do usuário.

Por exemplo, o formato geral Markdown envia dados com esta estrutura:

{
  "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"
}

O texto exato da mensagem depende do evento, do idioma do grupo, da configuração de notificações resumidas e da versão do Loomio. Use os campos de nível superior documentados para o formato selecionado, sem depender da redação das frases.

Pesquisa

Pesquise discussões, comentários, enquetes, votos e conclusões visíveis para o usuário da chave de API. Os resultados incluem conteúdo público mesmo que o usuário não seja membro do grupo. O conteúdo privado continua sujeito às regras normais de visibilidade do tópico.

GET /api/b2/search

Parâmetros

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/search?query=quarterly+planning&type=Discussion'

A resposta contém um array search_results. Cada resultado identifica o registro encontrado e seu contexto visível por meio de campos como searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at e tags. Os campos que não se aplicam a um resultado têm valor null.

Relatório de participação

Retorna os mesmos dados agregados de participação usados no relatório de participação do Loomio.

GET /api/b2/reports

Parâmetros

Uma pessoa é delegada quando tem uma associação ativa como delegada em qualquer um dos grupos selecionados. Suas contagens são agregadas em todos os grupos selecionados. Delegados aparecem no relatório mesmo quando todas as contagens de atividade são zero. As contagens incluem tópicos, comentários, enquetes, votos, conclusões e reações; elas não representam taxas de participação nas votações. Os registros de usuários também incluem os convites para votar em enquetes identificadas: quantos foram emitidos, atendidos e não atendidos. Enquetes anônimas ficam fora de todas as contagens de votos por pessoa. all_votes_cast só é verdadeiro quando pelo menos um convite para votar foi emitido e todos os convites emitidos resultaram em voto.

A API aplica as mesmas regras de visibilidade de grupos usadas pelo relatório no Loomio. Uma chave da API do usuário não pode expor dados de grupos aos quais esse usuário não tem acesso.

Exemplo

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'

O array users contém registros completos de atividade:

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

Criar discussão

Crie uma discussão usando a conta associada à chave de API.

POST /api/b2/discussions

Parâmetros

Exemplo

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

Consultar discussão

Consulte uma discussão pelo ID numérico ou pela chave de texto.

GET /api/b2/discussions/:id

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/discussions/abc123

Listar discussões

Liste as discussões de um grupo visíveis para o usuário da chave de API. Em um grupo público, quem não é membro pode listar as discussões públicas. As discussões privadas só ficam disponíveis para quem pode lê-las no Loomio.

GET /api/b2/discussions

Parâmetros

Compatibilidade: per e from são aceitos como alternativas a limit e offset e continuarão funcionando.

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/discussions?group_id=123'

Listar tópicos

Liste os tópicos de discussão e de enquete visíveis para o usuário da chave de API, ordenados pela atividade mais recente. O ID de um tópico é seu topic_id.

GET /api/b2/threads

Parâmetros

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads?limit=50&offset=0'

Ler tópico

Leia um tópico, sua sequência ordenada de eventos ou o documento Markdown completo com o conteúdo visível.

GET /api/b2/threads/:topic_id

GET /api/b2/threads/:topic_id/items

GET /api/b2/threads/:topic_id/markdown

Exemplo

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

O endpoint items retorna a sequência ordenada de eventos, incluindo comentários, enquetes, votos e conclusões visíveis. O endpoint markdown retorna todo o conteúdo visível do tópico em um único documento Markdown. As justificativas dos votos são incluídas somente quando estão visíveis para o usuário da chave de API.

Todos os endpoints de tópicos aplicam as mesmas permissões da interface do Loomio. A chave de API não dá acesso a um tópico que o usuário normalmente não pode abrir.

Editar discussão

Edite uma discussão usando a conta associada à chave de API. Aplicam-se as mesmas permissões do Loomio: o usuário precisa ter permissão para editar a discussão.

PATCH /api/b2/discussions/:id

Parâmetros

Exemplo

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

Excluir discussão sem remoção definitiva

Exclua uma discussão sem removê-la definitivamente, usando a conta associada à chave de API. A discussão é descartada, mas seu registro permanece.

DELETE /api/b2/discussions/:id

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/discussions/123

Criar comentário

Crie um comentário em uma discussão usando a conta associada à chave de API.

POST /api/b2/comments

Parâmetros

Exemplo

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

Editar comentário

Edite um comentário usando a conta associada à chave de API. Aplicam-se as mesmas permissões do Loomio: o usuário precisa ter permissão para editar o comentário.

PATCH /api/b2/comments/:id

Parâmetros

Exemplo

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

Excluir comentário sem remoção definitiva

Exclua um comentário sem removê-lo definitivamente, usando a conta associada à chave de API. O comentário é descartado e seu texto fica oculto, mas o registro permanece.

DELETE /api/b2/comments/:id

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/comments/123

Criar enquete

Crie uma enquete como o usuário da chave de API.

POST /api/b2/polls

Parâmetros

Exemplo

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

Consultar enquete

Consulte uma enquete pelo ID numérico ou pela chave em texto.

GET /api/b2/polls/:id

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/polls/abc123

Listar enquetes

Liste as enquetes de um grupo visíveis para o usuário da chave de API. Em um grupo público, quem não é membro pode listar as enquetes públicas. As enquetes privadas continuam acessíveis apenas a quem pode lê-las no Loomio. A resposta inclui a conclusão atual de cada enquete visível. Assim, você pode usar status=closed para listar propostas que já têm uma conclusão.

GET /api/b2/polls

Parâmetros

Compatibilidade: per e from são aceitos como alternativas a limit e offset e continuarão funcionando.

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/polls?group_id=123'

Editar enquete

Edite uma enquete como o usuário da chave de API. Aplicam-se as mesmas permissões do Loomio: o usuário precisa ter permissão para editar a enquete.

PATCH /api/b2/polls/:id

Parâmetros

Exemplo

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

Excluir enquete sem apagar o registro

Exclua uma enquete como o usuário da chave de API. A enquete será descartada, mas seu registro permanecerá armazenado.

DELETE /api/b2/polls/:id

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/polls/123

Listar associações ao grupo

Liste as associações ao grupo visíveis para o usuário da chave de API. Membros do grupo podem consultar nomes, IDs, títulos e funções dos membros. Os endereços de e-mail são incluídos apenas para a própria conta do usuário da chave de API ou quando esse usuário é administrador do grupo.

GET /api/b2/memberships

Parâmetros

Exemplo

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/memberships?group_id=123'

Gerenciar associações ao grupo

Envie uma lista de endereços de e-mail. Os endereços novos receberão um convite para o grupo. Ao contrário da consulta de associações, esta operação exige permissão de administrador do grupo.

POST /api/b2/memberships

Parâmetros

Exemplo

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

Se você enviar remove_absent=1, os membros do grupo que não estiverem na lista serão removidos. Tenha cuidado: isso pode remover todas as pessoas do seu grupo.

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

A resposta é um objeto com {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.