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

/api/b2 é a API voltada ao usuário 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 usam os vínculos de membro e as permissões de grupo do usuário da chave de API. Ser administrador da instância não amplia o acesso de uma chave de API a grupos ou conteúdos; use a API do servidor para administrar a instância.

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

Usuários conectados podem encontrar sua chave de API e os IDs dos grupos na página de acesso à API.

Envie a chave de API em um cabeçalho Authorization: Bearer. Chaves de API em parâmetros de consulta são rejeitadas porque as URLs podem ser registradas por proxies e logs de acesso.

Alteração na autenticação

Antes, a chave de API era aceita como um parâmetro api_key na URL. Requisições que usam ?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 da resposta e registros relacionados

As respostas da API do usuário usam um formato composto: os registros principais vêm acompanhados de registros relacionados, como conversas, grupos, usuários, enquetes e reações. Isso permite que um cliente preencha um armazenamento local de registros com uma única requisição, mas pode incluir mais dados do que uma integração simples precisa.

Passe compact=1 para omitir registros relacionados volumosos de conversas, grupos, grupos principais, vínculos de membros, reações, tags 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 diretamente as exclusões, passe exclude_types com os tipos de registro no singular, separados por espaços. Por exemplo, exclude_types=group reaction omite grupos e reações relacionados. Os 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 se aplicam aos registros relacionados, não ao recurso principal solicitado pelo endpoint.

As respostas de coleções incluem meta.total quando há um tamanho exato definido para a 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 nos quais o usuário da chave de API tem um vínculo de 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 principais e subgrupos, inclusive grupos cuja assinatura não está ativa no momento. Verifique o campo enabled quando uma integração deve operar apenas em grupos habilitados.

Os principais campos de grupo incluem:

A resposta pode incluir configurações adicionais do grupo, registros relacionados de grupos principais e os vínculos de membro do usuário da API. Os clientes devem ignorar os campos que não usam.

Obter um grupo

Retorna um grupo visível ao 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 requisição para um grupo que o usuário da chave de API não pode acessar retorna um erro de permissão.

Webhooks

A API do usuário funciona por requisições: uma integração chama o Loomio quando precisa ler ou alterar dados. Um webhook de grupo permite o envio na direção oposta. O Loomio envia os eventos selecionados do grupo ao seu endpoint assim que acontecem, para que a integração não precise consultar periodicamente a API REST em busca de alterações.

Os webhooks são configurados por grupo e exigem permissão de administrador do grupo. Eles podem ser gerenciados 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 que seu endpoint aceita. 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 que não possa ser adivinhada. O Loomio exige que o destino seja resolvido para um endereço público e bloqueia requisições para endereços de redes locais ou privadas.

Agentes e outras integrações também podem gerenciar webhooks pelos endpoints de chatbots com autenticação Bearer descritos abaixo. O recurso se chama chatbots para manter a compatibilidade com as integrações de bate-papo do Loomio, mas também representa webhooks gerais de saída.

Listar webhooks

Retorna as integrações de bate-papo configuradas para um grupo. O usuário da chave de API deve ser administrador desse grupo. A resposta inclui URLs de destino, portanto não deve ser exposta aos 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 deve ser administrador do grupo indicado por group_id. O destino é validado como uma URL pública antes de ser salvo.

Atualizar um webhook

PATCH /api/b2/chatbots/:id

Envie os campos que devem ser alterados. O webhook não pode ser transferido para outro grupo por meio da alteração de 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

Testar um destino de webhook

Envie uma mensagem de teste compatível com Markdown para um destino antes ou depois de salvar sua 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 as entregas futuras. Isso não exclui nenhum conteúdo do grupo no Loomio.

Tipos de evento

Um webhook pode se inscrever nestes tipos de evento:

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

Entrega HTTP

O Loomio envia um POST HTTP assíncrono 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. Os serviços que recebem webhooks devem responder rapidamente, processar tarefas mais demoradas de forma assíncrona e tolerar entregas duplicadas ou fora de ordem.

Atualmente, o Loomio não adiciona uma assinatura de webhook, um cabeçalho com segredo compartilhado, um ID de evento ou um ID de entrega. Trate a URL de destino completa como uma credencial, não a exponha publicamente e inclua na URL um token que não possa ser adivinhado quando o serviço receptor permitir. Se você precisar de um esquema de eventos estável e legível por máquina ou de entregas assinadas, use o webhook como uma notificação de alteração e obtenha os registros atuais pela API do usuário autenticada.

Formatos de payload

Os payloads de webhook são mensagens formatadas para exibição em serviços de bate-papo. Eles não são registros completos e serializados do Loomio. Os links na mensagem identificam o conteúdo afetado no Loomio; uma integração pode consultar a API do usuário quando precisar do estado atual em formato estruturado.

Por exemplo, o formato Markdown geral envia um corpo 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 para enviar apenas a notificação e da versão do Loomio. Os serviços receptores devem usar os campos de nível superior documentados para o formato selecionado, em vez de analisar a redação das frases.

Busca

Busque 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 quando o usuário não é membro do grupo correspondente; o conteúdo privado continua sujeito às regras normais de visibilidade das conversas.

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 correspondente e seu contexto visível com campos que incluem 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 são null.

Relatório de participação

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

GET /api/b2/reports

Parâmetros

Uma pessoa é delegada quando tem uma participação ativa como delegada em qualquer grupo selecionado. Suas contagens são agregadas em todos os grupos selecionados. As linhas dos delegados são retornadas mesmo quando todas as contagens de atividade são zero. As contagens abrangem conversas, comentários, enquetes, votos, conclusões e reações; elas não são taxas de participação nas votações. As linhas dos usuários também incluem cédulas de votação identificadas emitidas, usadas para votar e não usadas. As enquetes anônimas são excluídas de todas as contagens de votação por pessoa. all_votes_cast é verdadeiro somente quando pelo menos uma cédula foi emitida e todas as cédulas emitidas foram usadas para votar.

A API aplica as mesmas regras de visibilidade dos grupos que o relatório disponível no aplicativo. Uma chave da API do usuário não pode expor dados de relatório 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 linhas completas 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 como o usuário da 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

Exibir discussão

Obtenha uma discussão usando seu ID, um número inteiro, ou sua chave, uma string.

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 ao usuário da chave de API. Em um grupo visível publicamente, uma pessoa que não é membro pode listar suas discussões públicas; as discussões privadas continuam restritas aos usuários que podem lê-las no Loomio.

GET /api/b2/discussions

Parâmetros

Compatibilidade com versões anteriores: per e from são aceitos como aliases de 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 conversas

Liste as conversas de discussão e de enquete visíveis ao usuário da chave de API, ordenadas pela atividade mais recente. O ID de uma conversa é 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 conversa

Leia uma conversa, sua sequência ordenada de eventos ou seu 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 da conversa em um único documento Markdown. Os motivos dos votos são incluídos somente quando são visíveis ao usuário da chave de API.

Todos os endpoints de conversas aplicam as mesmas permissões da interface do Loomio. A chave de API não concede acesso a uma conversa que o usuário normalmente não pode abrir.

Editar discussão

Edite uma discussão como o usuário da chave de API. As mesmas permissões do Loomio se aplicam: o usuário deve ter permissão para editar essa 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 uma discussão logicamente

Exclua uma discussão logicamente como o usuário da chave de API. Isso descarta a discussão e mantém seu registro.

DELETE /api/b2/discussions/:id

Exemplo

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

Criar um comentário

Crie um comentário em uma discussão como o usuário da 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 um comentário

Edite um comentário como o usuário da chave de API. As mesmas permissões do Loomio se aplicam: o usuário deve ter permissão para editar esse 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 um comentário logicamente

Exclua um comentário logicamente como o usuário da chave de API. Isso descarta o comentário, oculta seu corpo e mantém seu registro.

DELETE /api/b2/comments/:id

Exemplo

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

Criar uma 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

Exibir enquete

Obtenha uma enquete usando seu ID, um inteiro, ou sua chave, uma string.

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 ao usuário da chave de API. Em um grupo visível publicamente, uma pessoa que não seja membro pode listar suas enquetes públicas; as enquetes privadas continuam restritas aos usuários que podem lê-las no Loomio. A resposta inclui a conclusão atual de cada enquete visível, então você pode usar status=closed para listar propostas já decididas.

GET /api/b2/polls

Parâmetros

Compatibilidade com versões anteriores: per e from são aceitos como aliases de 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 deve ter permissão para editar essa 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 logicamente

Exclua uma enquete logicamente como o usuário da chave de API. Isso descarta a enquete e mantém seu registro.

DELETE /api/b2/polls/:id

Exemplo

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

Listar vínculos de membros

Liste os vínculos de membros visíveis ao usuário da chave de API. Os membros do grupo podem consultar os 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 vínculos de membros

Envie uma lista de endereços de e-mail. Todos os novos endereços receberão um convite para o grupo. Ao contrário da listagem de vínculos de membros, 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ê passar remove_absent=1, todos os membros do grupo que não estiverem na lista serão removidos do grupo. Tenha cuidado: você 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

Isso retorna um objeto com {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.