Documentación de la API de usuario de Loomio

/api/b2 es la API de usuario para integraciones con Loomio. Usa la clave de API de una cuenta de usuario y realiza cada acción en nombre de esa persona.

Las operaciones de grupo se rigen por las pertenencias y los permisos de grupo de la persona titular de la clave de API. Ser administrador de la instancia no amplía el acceso de la clave a grupos ni a contenidos. Para administrar la instancia, usa la API de servidor.

Usa la clave de API de la cuenta de Loomio que realizará las acciones. Una cuenta de bot dedicada puede ser útil si la integración no debe recibir invitaciones a sondeos ni notificaciones.

Si has iniciado sesión, puedes encontrar tu clave de API y los identificadores de tus grupos en la página de acceso a la API.

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

Cambio en la autenticación

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

Authorization: Bearer YOUR_API_KEY

Los ejemplos usan YOUR_API_KEY, el identificador de grupo 123 y https://www.loomio.com/. Sustitúyelos por tu clave de API, el identificador 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 tienen un formato compuesto: los registros principales van acompañados de registros relacionados, como temas, grupos, usuarios, sondeos y reacciones. Así, un cliente puede llenar su almacén local de registros con una sola solicitud, aunque la respuesta puede incluir más datos de los que necesita una integración sencilla.

Usa compact=1 para omitir los temas, grupos, grupos principales, pertenencias, reacciones, etiquetas y traducciones relacionados que ocupan más espacio. Se mantienen los registros principales y los registros relacionados necesarios para interpretar su contenido.

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

Para controlar las exclusiones directamente, usa exclude_types con 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 conoce el 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 deliberadamente 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 la persona titular de la clave de API tiene una pertenencia 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, incluso si su suscripción no está activa en ese momento. Comprueba el campo enabled si la integración solo debe operar con grupos habilitados.

Estos son algunos campos importantes de los grupos:

La respuesta puede incluir otros ajustes del grupo, registros relacionados del grupo principal y las pertenencias de la persona titular de la clave de API. Los clientes deben ignorar los campos que no utilicen.

Obtener un grupo

Devuelve un grupo visible para la persona titular de la clave de API.

GET /api/b2/groups/:id_or_key_or_handle

Puedes identificar el grupo por su identificador numérico, clave o identificador legible.

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 usa los mismos campos que el endpoint de listado. Si la persona titular de la clave de API no puede acceder al grupo solicitado, se devuelve un error de permisos.

Webhooks

La API de usuario funciona mediante solicitudes: una integración llama a Loomio cuando quiere leer o cambiar datos. Un webhook de grupo permite recibir cambios automáticamente. Loomio envía a tu endpoint los eventos seleccionados del grupo cuando ocurren, por lo que la integración no necesita consultar periódicamente la API REST.

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 cuyo formato de datos acepte 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 difícil de adivinar. Loomio exige que el destino se 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 los webhooks mediante los endpoints de chatbots con autenticación Bearer descritos más abajo. 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. La persona titular de la clave de API debe ser administradora de ese grupo. La respuesta incluye las URL de destino, por lo que no debe mostrarse a integrantes sin permisos de administración.

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

La persona propietaria de la clave de API debe administrar el grupo indicado en group_id. Antes de guardar la configuración, se comprueba que el destino sea una URL pública.

Actualizar un webhook

PATCH /api/b2/chatbots/:id

Envía los campos que quieras cambiar. No puedes trasladar 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 al destino antes o después de guardar su 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

Al eliminar la configuración, se detienen los envíos futuros. No se elimina ningún contenido del grupo en 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. También se puede seleccionar explícitamente la integración al compartir contenido o enviar ciertas notificaciones, aunque no se haya seleccionado el evento automático correspondiente.

Entrega HTTP

Loomio envía una solicitud HTTP POST asíncrona a la URL configurada con este encabezado:

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

La solicitud tiene un tiempo de espera de cinco segundos. Una respuesta 2xx, incluida 204 No Content, se considera correcta. Los servicios que reciben webhooks deben responder con rapidez, procesar de forma asíncrona las tareas más largas y admitir entregas duplicadas o fuera de orden.

Actualmente, Loomio no añade una firma al webhook, un encabezado con un secreto compartido, un ID de evento ni un ID de entrega. Trata la URL de destino completa como una credencial, no la publiques e incluye en ella un token difícil de adivinar si el servicio receptor lo admite. Si necesitas un esquema de eventos estable y legible por máquina o entregas firmadas, usa el webhook como aviso de cambios y consulta los registros actuales mediante la API de usuario autenticada.

Formatos de los datos enviados

Los datos enviados por los webhooks son mensajes preparados para servicios de chat. No contienen registros completos de Loomio en formato serializado. Los enlaces del mensaje identifican el contenido de Loomio afectado; una integración puede consultar después la API de usuario si necesita datos estructurados y actualizados.

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, el idioma del grupo, la configuración de solo notificaciones y la versión de Loomio. Los servicios receptores deben utilizar los campos de nivel superior documentados para el formato seleccionado, en lugar de analizar el texto de las frases.

Buscar

Busca discusiones, comentarios, sondeos, votos y conclusiones visibles para la persona propietaria de la clave de API. Los resultados incluyen contenido público aunque esa persona no pertenezca al grupo. 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 su contexto visible 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 corresponden 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 si tiene una membresía activa como delegada en cualquiera de los grupos seleccionados. Sus recuentos se agregan entre todos esos grupos. Se devuelven filas de personas delegadas incluso cuando todos sus recuentos de actividad son cero. Los recuentos incluyen hilos, comentarios, sondeos, votos, conclusiones y reacciones; no representan tasas de participación en las votaciones. Las filas de personas también incluyen las papeletas identificadas emitidas, depositadas y no respondidas. Los sondeos anónimos se excluyen de todos los recuentos de votos por persona. all_votes_cast solo es verdadero si se emitió al menos una papeleta y se depositaron todas las emitidas.

La API aplica las mismas reglas de visibilidad de grupos que el informe de Loomio. Una clave de la API de usuario no puede mostrar datos de informes de grupos a los que esa persona no tiene acceso.

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 con la cuenta a la que pertenece la clave de 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

Consultar una discusión

Consulta una discusión mediante su ID numérico o su clave 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 que puede ver la cuenta a la que pertenece la clave de API. Si el grupo es público, una persona que no sea miembro puede listar sus discusiones públicas. Las discusiones privadas solo están disponibles para quienes pueden leerlas en Loomio.

GET /api/b2/discussions

Parámetros

Por compatibilidad, 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 discusiones y sondeos que puede ver la cuenta a la que pertenece la clave de API, ordenados por actividad más reciente. El ID de un hilo es su 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, su secuencia ordenada de eventos o el documento Markdown completo que puedes ver.

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, sondeos, votos y conclusiones visibles. El endpoint markdown devuelve todo el contenido visible del hilo en un único documento Markdown. Las razones de los votos solo se incluyen cuando la cuenta a la que pertenece la clave de API puede verlas.

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

Editar una discusión

Edita una discusión con la cuenta a la que pertenece la clave de API. Se aplican los mismos permisos que en Loomio: la cuenta 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 sin borrar su registro

Elimina una discusión con la cuenta a la que pertenece la clave de API. La discusión se descarta, pero su registro se conserva.

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 con la cuenta a la que pertenece 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 con la cuenta a la que pertenece la clave de API. Se aplican los mismos permisos que en Loomio: la cuenta 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 sin borrar su registro

Elimina un comentario con la cuenta a la que pertenece la clave de API. El comentario se descarta y su texto se oculta, pero su registro se conserva.

DELETE /api/b2/comments/:id

Ejemplo

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

Crear un sondeo

Crea un sondeo con el usuario al que pertenece 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

Consultar un sondeo

Obtén un sondeo mediante su ID numérico o su clave de texto.

GET /api/b2/polls/:id

Ejemplo

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

Listar sondeos

Lista los sondeos de un grupo visibles para el usuario al que pertenece la clave de API. Si el grupo es público, una persona que no sea miembro puede listar sus sondeos públicos. Los sondeos privados solo están disponibles para quienes pueden leerlos en Loomio. La respuesta incluye la conclusión actual de cada sondeo visible, por lo que puedes usar status=closed para listar las propuestas ya decididas.

GET /api/b2/polls

Parámetros

Por compatibilidad, 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 un sondeo

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

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 un sondeo sin borrar su registro

Elimina un sondeo con el usuario al que pertenece la clave de API. El sondeo se descarta, pero se conserva su registro.

DELETE /api/b2/polls/:id

Ejemplo

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

Listar miembros

Lista las membresías visibles para el usuario al que pertenece la clave de API. Los miembros del grupo pueden ver los nombres, ID, cargos y roles de los demás miembros. Las direcciones de correo electrónico solo se incluyen para la cuenta del propio usuario o si este administra el 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 miembros

Envía una lista de direcciones de correo electrónico. Se invitará al grupo a todas las direcciones nuevas. Esta operación requiere permisos de administración 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á del grupo a 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

La respuesta es un objeto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.