Documentación de la API de usuario de Loomio

/api/b2 es la API orientada a usuarios para integraciones con Loomio. Utiliza la clave de API de una cuenta de usuario y cada acción se realiza como ese usuario.

Las operaciones de grupo utilizan las membresías y los permisos de grupo del usuario de la clave de API. Ser administrador de la instancia no amplía el acceso de una clave de API a grupos o contenido; usa la API de servidor para administrar la instancia.

Usa la clave de API de la cuenta de usuario de Loomio que realizará las acciones. Una cuenta dedicada para un bot resulta útil cuando una integración no debe recibir invitaciones a encuestas ni notificaciones.

Los usuarios que han iniciado sesión pueden encontrar la clave de API y los ID de grupo en la página de acceso a la API.

Envía la clave de API en una cabecera Authorization: Bearer. Las claves de API en cadenas de consulta se rechazan porque los proxies y los registros de acceso pueden guardar las URL.

Cambio en la autenticación

Antes se aceptaba la clave de API como parámetro api_key de la URL. Las solicitudes que utilizan ?api_key=YOUR_API_KEY ya no funcionan. Usa la cabecera HTTP Authorization en su lugar:

Authorization: Bearer YOUR_API_KEY

Los ejemplos utilizan YOUR_API_KEY, el ID de grupo 123 y https://www.loomio.com/. Sustitúyelos por tu clave de API, el ID de tu grupo y la URL de tu instalación de Loomio.

Tamaño de las respuestas y registros relacionados

Las respuestas de la API de usuario utilizan un formato compuesto: los registros principales van acompañados de registros relacionados, como temas, grupos, usuarios, encuestas y reacciones. Esto permite que un cliente complete un almacén local de registros con una sola solicitud, pero puede incluir más datos de los que necesita una integración sencilla.

Pasa compact=1 para omitir los registros relacionados voluminosos de temas, grupos, grupos principales, membresías, reacciones, etiquetas y traducciones. Los registros principales y los registros relacionados necesarios para interpretar el contenido siguen presentes.

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

Para tener un control directo, pasa exclude_types con los tipos de registro en singular separados por espacios. Por ejemplo, exclude_types=group reaction omite los grupos y las reacciones relacionados. Los valores habituales son topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome y topic_item. Las exclusiones se aplican a los registros relacionados, no al recurso principal solicitado al endpoint.

Las respuestas de colecciones incluyen meta.total cuando se define un tamaño exacto de la colección. El total se calcula antes de aplicar limit y offset. Los endpoints, como el de búsqueda, que devuelven intencionadamente un conjunto limitado de resultados omiten meta.total en lugar de devolver null.

Resumen de endpoints

Grupos

Listar grupos

Devuelve los grupos en los que el usuario de la clave de API tiene una membresía activa.

GET /api/b2/groups

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

La respuesta contiene todos los registros coincidentes en un array groups sin paginación. Incluye grupos principales y subgrupos, incluidos los grupos cuya suscripción no está activa actualmente. Comprueba el campo enabled cuando una integración deba operar solo en grupos habilitados.

Entre los campos importantes de los grupos se incluyen:

La respuesta puede incluir ajustes adicionales del grupo, registros relacionados del grupo principal y las membresías del usuario de la API. Los clientes deben ignorar los campos que no utilizan.

Obtener un grupo

Devuelve un grupo visible para el usuario de la clave de API.

GET /api/b2/groups/:id_or_key_or_handle

El identificador puede ser el ID numérico, la clave o el identificador legible del 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

La respuesta contiene el grupo en el array groups y utiliza los mismos campos que el endpoint de listado. Una solicitud de un grupo al que el usuario de la clave de API no puede acceder devuelve un error de permisos.

Webhooks

La API de usuario se basa en solicitudes: una integración llama a Loomio cuando quiere leer o modificar datos. Un webhook de grupo permite enviar los datos en la dirección contraria. Loomio envía los eventos seleccionados del grupo a tu endpoint a medida que ocurren, por lo que una integración no necesita consultar periódicamente la API REST para detectar cambios.

Los webhooks se configuran por grupo y requieren permisos de administrador del grupo. Puedes gestionarlos desde la interfaz de Loomio:

1. Abre el grupo.
2. Abre el menú del grupo y selecciona Integraciones de chat.
3. Añade la integración que coincida con el formato de datos que acepta tu endpoint. Para un endpoint de uso general, usa el formato Mattermost/Markdown.
4. Introduce un nombre y la URL de destino.
5. Selecciona los eventos que Loomio debe enviar automáticamente.
6. Guarda la integración y usa Conexión de prueba para enviar un mensaje de prueba.

Usa un destino HTTPS con una URL que no se pueda adivinar. Loomio exige que el destino resuelva a una dirección pública y bloquea las solicitudes a direcciones de redes locales o privadas.

Los agentes y otras integraciones también pueden gestionar webhooks mediante los endpoints de chatbots con autenticación Bearer descritos a continuación. El recurso se llama chatbots por compatibilidad con las integraciones de chat de Loomio, pero también representa webhooks salientes de uso general.

Listar webhooks

Devuelve las integraciones de chat configuradas para un grupo. El usuario de la clave de API debe ser administrador de ese grupo. La respuesta incluye las URL de destino, por lo que no debe exponerse a los miembros del grupo que no sean administradores.

GET /api/b2/chatbots?group_id=123

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

La respuesta contiene un array chatbots con estos campos:

Crear un 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

El usuario de la clave de API debe ser administrador del grupo indicado por group_id. Antes de guardar el destino, se comprueba que sea una URL pública.

Actualizar un webhook

PATCH /api/b2/chatbots/:id

Envía los campos que deban cambiar. No se puede transferir el webhook a otro grupo cambiando 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

Probar el destino de un webhook

Envía un mensaje de prueba compatible con Markdown a un destino antes o después de guardar la configuración.

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

Eliminar un webhook

DELETE /api/b2/chatbots/:id

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

Eliminar la configuración detiene los envíos futuros. No elimina ningún contenido del grupo de Loomio.

Tipos de eventos

Un webhook puede suscribirse a estos tipos de eventos:

El webhook pertenece a un grupo y recibe los eventos de ese grupo a los que está suscrito. Las personas también pueden seleccionar explícitamente la integración al compartir o enviar algunas notificaciones, incluso cuando el evento automático correspondiente no está seleccionado.

Envío HTTP

Loomio envía una petición HTTP POST asíncrona a la URL configurada con esta cabecera:

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

El tiempo de espera de la petición es de cinco segundos. Una respuesta 2xx, incluida 204 No Content, se considera satisfactoria. Los servicios que reciben webhooks deben responder con rapidez, procesar las tareas más largas de forma asíncrona y admitir envíos duplicados o fuera de orden.

Actualmente, Loomio no añade una firma del webhook, una cabecera con un secreto compartido, un ID de evento ni un ID de envío. Trata la URL de destino completa como una credencial, no la expongas públicamente e incluye en ella un token que no se pueda adivinar cuando el servicio receptor lo admita. Si necesitas un esquema de eventos estable y legible por máquinas o un envío firmado, usa el webhook como notificación de cambios y obtén los registros actuales mediante la API de usuario autenticada.

Formatos de los datos enviados

Los datos enviados por los webhooks son mensajes destinados a servicios de chat y preparados para mostrarse. No son registros completos serializados de Loomio. Los enlaces del mensaje identifican el contenido de Loomio afectado; una integración puede consultar después la API de usuario cuando necesite el estado actual en un formato estructurado.

Por ejemplo, el formato general de Markdown envía un cuerpo con esta estructura:

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

El texto exacto del mensaje depende del evento, la configuración regional del grupo, el ajuste de solo notificaciones y la versión de Loomio. Los servicios receptores deben basarse en los campos de nivel superior documentados del formato seleccionado, en lugar de analizar la redacción de las frases.

Buscar

Busca discusiones, comentarios, encuestas, votos y conclusiones visibles para el usuario de la clave API. Los resultados incluyen contenido público incluso cuando el usuario no es miembro del grupo al que pertenece ese contenido; el contenido privado sigue sujeto a las reglas habituales de visibilidad de los temas.

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'

La respuesta contiene un array search_results. Cada resultado identifica el registro coincidente y el contexto visible de ese registro mediante campos como searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at y tags. Los campos que no se aplican a un resultado tienen el valor null.

Informe de participación

Devuelve los mismos datos agregados de participación que utiliza el informe de participación de Loomio.

GET /api/b2/reports

Parámetros

Una persona es delegada cuando tiene una membresía activa como delegada en cualquiera de los grupos seleccionados. Sus recuentos se agregan para todos los grupos seleccionados. Se devuelven las filas de los delegados incluso cuando todos los recuentos de actividad son cero. Los recuentos abarcan hilos, comentarios, encuestas, votos, conclusiones y reacciones; no son tasas de participación en las votaciones. Las filas de usuarios también incluyen las papeletas de votaciones identificadas que se han emitido, utilizado para votar o dejado sin utilizar. Las encuestas anónimas se excluyen de todos los recuentos de votación por persona. all_votes_cast es verdadero solo cuando se ha emitido al menos una papeleta y se han utilizado todas las papeletas emitidas para votar.

La API aplica las mismas reglas de visibilidad de los grupos que el informe de la aplicación. Una clave de la API de usuario no puede revelar datos del informe de grupos a los que ese usuario no puede acceder.

Ejemplo

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'

El array users contiene filas completas de actividad:

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

Crear una discusión

Crea una discusión como el usuario de la clave API.

POST /api/b2/discussions

Parámetros

Ejemplo

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

Mostrar una discusión

Obtén una discusión usando el ID de la discusión, un número entero, o la clave, una cadena de texto.

GET /api/b2/discussions/:id

Ejemplo

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

Listar discusiones

Lista las discusiones de un grupo visibles para el usuario de la clave API. En un grupo visible públicamente, una persona que no sea miembro puede listar las discusiones públicas del grupo; las discusiones privadas siguen restringidas a los usuarios que pueden leerlas en Loomio.

GET /api/b2/discussions

Parámetros

Compatibilidad con versiones anteriores: per y from se aceptan como alias de limit y offset y seguirán funcionando.

Ejemplo

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

Listar hilos

Lista los hilos de discusión y de encuesta visibles para el usuario de la clave API, ordenados por la actividad más reciente. El ID de un hilo es el valor de topic_id.

GET /api/b2/threads

Parámetros

Ejemplo

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

Leer un hilo

Lee un hilo, la secuencia ordenada de eventos del hilo o el documento Markdown con todo el contenido visible del hilo.

GET /api/b2/threads/:topic_id

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

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

Ejemplo

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

El endpoint items devuelve la secuencia ordenada de eventos, incluidos los comentarios, las encuestas, los votos y las conclusiones visibles. El endpoint markdown devuelve todo el contenido visible del hilo en un único documento Markdown. Los motivos de los votos solo se incluyen cuando son visibles para el usuario de la clave API.

Todos los endpoints de hilos aplican los mismos permisos que la interfaz de Loomio. La clave API no concede acceso a un hilo que el usuario no pueda abrir normalmente.

Editar una discusión

Edita una discusión como el usuario de la clave API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar esa discusión.

PATCH /api/b2/discussions/:id

Parámetros

Ejemplo

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

Eliminar una discusión de forma lógica

Elimina una discusión de forma lógica como el usuario de la clave de API. Esto descarta la discusión y conserva el registro de la discusión.

DELETE /api/b2/discussions/:id

Ejemplo

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

Crear un comentario

Crea un comentario en una discusión como el usuario de la clave de API.

POST /api/b2/comments

Parámetros

Ejemplo

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 un comentario

Edita un comentario como el usuario de la clave de API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar ese comentario.

PATCH /api/b2/comments/:id

Parámetros

Ejemplo

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

Eliminar un comentario de forma lógica

Elimina un comentario de forma lógica como el usuario de la clave de API. Esto descarta el comentario, oculta el cuerpo del comentario y conserva el registro del comentario.

DELETE /api/b2/comments/:id

Ejemplo

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

Crear una encuesta

Crea una encuesta como el usuario de la clave de API.

POST /api/b2/polls

Parámetros

Ejemplo

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

Mostrar una encuesta

Obtén una encuesta mediante el ID de la encuesta, un entero, o la clave, una cadena de texto.

GET /api/b2/polls/:id

Ejemplo

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

Listar encuestas

Lista las encuestas de un grupo visibles para el usuario de la clave API. En un grupo visible públicamente, una persona que no sea miembro puede listar las encuestas públicas; las encuestas privadas siguen restringidas a los usuarios que pueden leerlas en Loomio. La respuesta incluye la conclusión actual de cada encuesta visible, por lo que puedes usar status=closed para listar las propuestas sobre las que ya se ha tomado una decisión.

GET /api/b2/polls

Parámetros

Compatibilidad con versiones anteriores: per y from se aceptan como alias de limit y offset y seguirán funcionando.

Ejemplo

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

Editar una encuesta

Edita una encuesta como el usuario de la clave API. Se aplican los mismos permisos que en Loomio: el usuario debe tener permiso para editar esa encuesta.

PATCH /api/b2/polls/:id

Parámetros

Ejemplo

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

Eliminar una encuesta de forma lógica

Elimina una encuesta de forma lógica como el usuario de la clave API. Esto descarta la encuesta y conserva el registro de la encuesta.

DELETE /api/b2/polls/:id

Ejemplo

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

Listar membresías

Lista las membresías visibles para el usuario de la clave de API. Los miembros del grupo pueden consultar los nombres, los ID, los títulos y los roles de los miembros. Las direcciones de correo electrónico solo se incluyen para la cuenta del propio usuario de la clave de API o cuando ese usuario es administrador del grupo.

GET /api/b2/memberships

Parámetros

Ejemplo

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

Gestionar membresías

Envía una lista de direcciones de correo electrónico. Se enviará una invitación al grupo a todas las direcciones nuevas. A diferencia de la consulta de membresías, esta operación requiere permisos de administrador del grupo.

POST /api/b2/memberships

Parámetros

Ejemplo

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

Si pasas remove_absent=1, se eliminarán del grupo todos los miembros que no estén incluidos en la lista. Ten cuidado, podrías eliminar a todos los miembros de tu 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

Esto devuelve un objeto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.