Documentation de l’API utilisateur de Loomio

/api/b2 est l’API destinée aux intégrations utilisateur avec Loomio. Elle utilise la clé API d’un compte utilisateur, et chaque action est effectuée au nom de ce compte.

Les opérations sur les groupes dépendent des adhésions et des autorisations de groupe de l’utilisateur auquel appartient la clé API. Le statut d’administrateur de l’instance n’étend pas l’accès de cette clé aux groupes ou aux contenus. Pour administrer l’instance, utilisez l’API serveur.

Utilisez la clé API du compte Loomio qui effectuera les actions. Un compte robot dédié est utile si l’intégration ne doit pas être invitée aux sondages ni recevoir de notifications.

Les utilisateurs connectés trouveront leur clé API et les identifiants de leurs groupes sur la page d’accès à l’API.

Envoyez la clé API dans l’en-tête Authorization: Bearer. Les clés API placées dans les paramètres d’URL sont rejetées, car les URL peuvent être enregistrées par les serveurs mandataires et les journaux d’accès.

Changement du mode d’authentification

La clé API était auparavant acceptée dans le paramètre d’URL api_key. Les requêtes utilisant ?api_key=YOUR_API_KEY ne fonctionnent plus. Utilisez désormais l’en-tête HTTP Authorization :

Authorization: Bearer YOUR_API_KEY

Les exemples utilisent YOUR_API_KEY, l’identifiant de groupe 123 et https://www.loomio.com/. Remplacez-les par votre clé API, l’identifiant de votre groupe et l’URL de votre installation Loomio.

Taille des réponses et enregistrements associés

Les réponses de l’API utilisateur ont un format composé : les enregistrements principaux sont accompagnés d’enregistrements associés, comme les sujets, les groupes, les utilisateurs, les sondages et les réactions. Un client peut ainsi remplir son stockage local avec une seule requête. La réponse peut toutefois contenir plus de données que nécessaire pour une intégration simple.

Ajoutez compact=1 pour omettre les sujets, groupes, groupes parents, adhésions, réactions, étiquettes et traductions associés les plus volumineux. Les enregistrements principaux et les enregistrements associés nécessaires pour comprendre leur contenu restent présents.

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

Pour choisir les exclusions, utilisez exclude_types avec des types d’enregistrements au singulier, séparés par des espaces. Par exemple, exclude_types=group reaction omet les groupes et les réactions associés. Les valeurs courantes sont topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome et topic_item. Les exclusions concernent les enregistrements associés, pas la ressource principale demandée à l’endpoint.

Les réponses contenant une collection incluent meta.total lorsque sa taille exacte est définie. Ce total est calculé avant l’application de limit et offset. Les endpoints comme la recherche, qui renvoient volontairement un ensemble limité de résultats, omettent meta.total au lieu de renvoyer null.

Résumé des endpoints

Groupes

Lister les groupes

Renvoie les groupes dont l’utilisateur auquel appartient la clé API est un membre actif.

GET /api/b2/groups

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

La réponse contient tous les enregistrements correspondants dans un tableau groups non paginé. Elle inclut les groupes parents et les sous-groupes, même lorsque leur abonnement n’est pas actif. Vérifiez le champ enabled si l’intégration ne doit agir que sur les groupes activés.

Les principaux champs d’un groupe sont :

La réponse peut aussi inclure d’autres paramètres du groupe, des enregistrements associés au groupe parent et les adhésions de l’utilisateur de l’API. Les clients doivent ignorer les champs qu’ils n’utilisent pas.

Obtenir un groupe

Renvoie un groupe visible par l’utilisateur auquel appartient la clé API.

GET /api/b2/groups/:id_or_key_or_handle

Vous pouvez identifier le groupe par son identifiant numérique, sa clé ou son identifiant lisible.

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 réponse contient le groupe dans le tableau groups, avec les mêmes champs que l’endpoint de liste. Une requête portant sur un groupe inaccessible à l’utilisateur auquel appartient la clé API renvoie une erreur d’autorisation.

Webhooks

L’API utilisateur fonctionne par requêtes : une intégration appelle Loomio lorsqu’elle veut lire ou modifier des données. Un webhook de groupe permet de recevoir les changements. Loomio envoie à votre endpoint les événements sélectionnés dès qu’ils se produisent. L’intégration n’a donc pas besoin d’interroger régulièrement l’API REST.

Les webhooks sont configurés par groupe et nécessitent les droits d’administrateur du groupe. Vous pouvez les gérer dans l’interface Loomio :

1. Ouvrez le groupe.
2. Ouvrez le menu du groupe et sélectionnez Intégrations de chat.
3. Ajoutez l’intégration correspondant au format de données accepté par votre endpoint. Pour un endpoint généraliste, utilisez le format Mattermost/Markdown.
4. Saisissez un nom et l’URL de destination.
5. Sélectionnez les événements que Loomio doit envoyer automatiquement.
6. Enregistrez l’intégration, puis utilisez Tester la connexion pour envoyer un message de test.

Utilisez une destination HTTPS dont l’URL est impossible à deviner. Loomio exige que cette URL mène à une adresse publique et bloque les requêtes vers les adresses de réseaux locaux ou privés.

Les agents et autres intégrations peuvent aussi gérer les webhooks au moyen des endpoints chatbot décrits ci-dessous, avec une authentification Bearer. La ressource s’appelle chatbots pour rester compatible avec les intégrations de chat de Loomio, mais elle représente également les webhooks sortants généraux.

Lister les webhooks

Renvoie les intégrations de chat configurées pour un groupe. L’utilisateur auquel appartient la clé API doit être administrateur de ce groupe. La réponse contient les URL de destination : elle ne doit donc pas être accessible aux membres ordinaires du groupe.

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 réponse contient un tableau chatbots avec les champs suivants :

Créer 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

Le compte associé à la clé API doit administrer le groupe désigné par group_id. L’URL de destination doit être publique pour que la configuration puisse être enregistrée.

Modifier un webhook

PATCH /api/b2/chatbots/:id

Envoyez les champs à modifier. Modifier group_id ne permet pas de transférer le webhook vers un autre groupe.

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

Tester la destination d’un webhook

Envoyez un message de test compatible avec Markdown à une destination, avant ou après l’enregistrement de sa configuration.

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

Supprimer un webhook

DELETE /api/b2/chatbots/:id

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

La suppression de la configuration arrête les envois futurs. Elle ne supprime aucun contenu du groupe dans Loomio.

Types d’événements

Un webhook peut recevoir les types d’événements suivants :

Le webhook appartient à un groupe et reçoit les événements sélectionnés de ce groupe. Une personne peut aussi sélectionner explicitement l’intégration lors du partage ou de l’envoi de certaines notifications, même si l’événement automatique correspondant n’est pas sélectionné.

Envoi HTTP

Loomio envoie une requête HTTP POST asynchrone à l’URL configurée avec cet en-tête :

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

Le délai d’expiration de la requête est de cinq secondes. Une réponse 2xx, y compris 204 No Content, est considérée comme une réussite. Les services qui reçoivent les webhooks doivent répondre rapidement, traiter les tâches longues de manière asynchrone et accepter les envois en double ou dans le désordre.

Actuellement, Loomio n’ajoute ni signature de webhook, ni en-tête contenant un secret partagé, ni identifiant d’événement ou d’envoi. Traitez l’URL de destination complète comme un secret : ne la rendez pas publique et ajoutez-y un jeton difficile à deviner si le service destinataire le permet. Si vous avez besoin d’un schéma d’événement stable et exploitable par machine ou d’envois signés, utilisez le webhook pour signaler un changement, puis récupérez les données à jour avec l’API utilisateur authentifiée.

Formats des données envoyées

Les données envoyées par les webhooks sont des messages destinés aux services de chat. Elles ne contiennent pas des enregistrements Loomio complets. Les liens du message indiquent le contenu Loomio concerné. Une intégration peut ensuite utiliser l’API utilisateur si elle a besoin de données structurées à jour.

Par exemple, le format Markdown général envoie un corps de cette forme :

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

Le texte exact du message dépend de l’événement, de la langue du groupe, du réglage qui limite le message au titre de la notification et de la version de Loomio. Les services destinataires doivent utiliser les champs de premier niveau documentés pour le format choisi, sans analyser la formulation des phrases.

Recherche

Recherchez les discussions, commentaires, sondages, votes et conclusions visibles par le compte associé à la clé API. Les résultats incluent le contenu public, même si ce compte n’est pas membre du groupe concerné. La visibilité du contenu privé reste soumise aux autorisations habituelles des sujets.

GET /api/b2/search

Paramètres

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

La réponse contient un tableau search_results. Chaque résultat indique l’enregistrement correspondant et son contexte visible, avec notamment les champs searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at et tags. Les champs sans objet pour un résultat ont la valeur null.

Rapport de participation

Renvoie les mêmes données de participation agrégées que le rapport de participation de Loomio.

GET /api/b2/reports

Paramètres

Une personne est déléguée si elle possède un rôle de délégué actif dans au moins un groupe sélectionné. Ses nombres d’activités sont agrégés sur tous les groupes sélectionnés. Les lignes des délégués sont renvoyées même si tous ces nombres sont nuls. Ils couvrent les fils de discussion, les commentaires, les sondages, les votes, les conclusions et les réactions. Ils ne représentent pas des taux de participation aux votes. Les lignes des utilisateurs indiquent aussi les bulletins de vote nominatif envoyés, déposés et non déposés. Les sondages anonymes sont exclus de tous les nombres de votes par personne. all_votes_cast vaut true uniquement si au moins un bulletin a été envoyé et que tous les bulletins envoyés ont été déposés.

L’API applique les mêmes règles de visibilité des groupes que le rapport dans Loomio. Une clé de l’API utilisateur ne peut pas révéler les données d’un groupe auquel le compte associé n’a pas accès.

Exemple

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'

Le tableau users contient des lignes d’activité complètes :

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

Créer une discussion

Créez une discussion avec le compte associé à la clé API.

POST /api/b2/discussions

Paramètres

Exemple

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

Afficher une discussion

Récupérez une discussion à l’aide de son identifiant numérique ou de sa clé, qui est une chaîne de caractères.

GET /api/b2/discussions/:id

Exemple

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

Lister les discussions

Listez les discussions d’un groupe visibles par le compte associé à la clé API. Si le groupe est public, une personne qui n’en est pas membre peut lister ses discussions publiques. Les discussions privées restent accessibles uniquement aux personnes autorisées à les consulter dans Loomio.

GET /api/b2/discussions

Paramètres

Compatibilité : per et from restent acceptés comme alias de limit et offset.

Exemple

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

Lister les fils de discussion

Listez les fils de discussion et les fils de sondage visibles par le compte associé à la clé API, du plus récemment actif au moins récemment actif. L’identifiant d’un fil est son topic_id.

GET /api/b2/threads

Paramètres

Exemple

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

Lire un fil de discussion

Lisez un fil de discussion, la liste chronologique de ses événements ou son contenu visible complet au format Markdown.

GET /api/b2/threads/:topic_id

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

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

Exemple

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

Le point de terminaison items renvoie les événements dans l’ordre, notamment les commentaires, sondages, votes et conclusions visibles. Le point de terminaison markdown renvoie tout le contenu visible du fil dans un seul document Markdown. Les motifs des votes ne sont inclus que s’ils sont visibles par le compte associé à la clé API.

Tous les points de terminaison des fils de discussion appliquent les mêmes permissions que l’interface Loomio. La clé API ne donne pas accès à un fil que l’utilisateur ne peut normalement pas ouvrir.

Modifier une discussion

Modifiez une discussion avec le compte associé à la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier cette discussion.

PATCH /api/b2/discussions/:id

Paramètres

Exemple

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

Supprimer une discussion sans effacer son enregistrement

Supprimez une discussion avec le compte associé à la clé API. La discussion est écartée, mais son enregistrement est conservé.

DELETE /api/b2/discussions/:id

Exemple

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

Créer un commentaire

Créez un commentaire dans une discussion avec le compte associé à la clé API.

POST /api/b2/comments

Paramètres

Exemple

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

Modifier un commentaire

Modifiez un commentaire avec le compte associé à la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier ce commentaire.

PATCH /api/b2/comments/:id

Paramètres

Exemple

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

Supprimer un commentaire sans effacer son enregistrement

Supprimez un commentaire avec le compte associé à la clé API. Le commentaire est écarté et son contenu masqué, mais son enregistrement est conservé.

DELETE /api/b2/comments/:id

Exemple

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

Créer un sondage

Créez un sondage avec le compte utilisateur associé à la clé API.

POST /api/b2/polls

Paramètres

Exemple

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

Consulter un sondage

Récupérez un sondage à partir de son identifiant numérique ou de sa clé, qui est une chaîne de caractères.

GET /api/b2/polls/:id

Exemple

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

Lister les sondages

Listez les sondages d’un groupe visibles pour le compte utilisateur associé à la clé API. Dans un groupe public, une personne qui n’en est pas membre peut lister les sondages publics. Les sondages privés restent réservés aux personnes autorisées à les consulter dans Loomio. La réponse inclut la conclusion actuelle de chaque sondage visible. Vous pouvez donc utiliser status=closed pour lister les propositions ayant fait l’objet d’une décision.

GET /api/b2/polls

Paramètres

Compatibilité : per et from restent acceptés comme alias de limit et offset.

Exemple

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

Modifier un sondage

Modifiez un sondage avec le compte utilisateur associé à la clé API. Les mêmes autorisations que dans Loomio s’appliquent : ce compte doit être autorisé à modifier le sondage.

PATCH /api/b2/polls/:id

Paramètres

Exemple

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

Supprimer un sondage sans effacer son enregistrement

Supprimez un sondage avec le compte utilisateur associé à la clé API. Le sondage est écarté, mais son enregistrement est conservé.

DELETE /api/b2/polls/:id

Exemple

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

Lister les adhésions

Listez les adhésions visibles pour le compte utilisateur associé à la clé API. Les membres d’un groupe peuvent consulter les noms, les identifiants, les titres et les rôles des membres. Les adresses e-mail sont incluses uniquement pour le propre compte associé à la clé API ou lorsque ce compte est administrateur du groupe.

GET /api/b2/memberships

Paramètres

Exemple

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

Gérer les adhésions

Envoyez une liste d’adresses e-mail. Chaque nouvelle adresse recevra une invitation à rejoindre le groupe. Contrairement à la consultation des adhésions, cette opération nécessite les droits d’administration du groupe.

POST /api/b2/memberships

Paramètres

Exemple

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 vous fournissez remove_absent=1, les membres du groupe absents de la liste seront retirés du groupe. Vérifiez la liste : vous pourriez retirer tous les membres de votre groupe.

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 réponse est un objet contenant {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.