Documentation de l’API utilisateur de Loomio

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

Les opérations sur les groupes utilisent les adhésions et les permissions dans les groupes de l’utilisateur associé à la clé API. Le statut d’administrateur de l’instance n’étend pas l’accès d’une clé API aux groupes ou au contenu ; utilisez l’API serveur pour l’administration de l’instance.

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

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

Envoyez la clé API dans un en-tête Authorization: Bearer. Les clés API dans les chaînes de requête sont rejetées, car les URL peuvent être enregistrées par les serveurs mandataires et dans les journaux d’accès.

Changement d’authentification

La clé API était auparavant acceptée comme 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 ces valeurs 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 utilisent un format composé : les enregistrements principaux sont accompagnés d’enregistrements associés, tels que des sujets, des groupes, des utilisateurs, des sondages et des réactions. Cela permet à un client d’alimenter un stockage local d’enregistrements à partir d’une seule requête, mais peut inclure plus de données qu’une intégration simple n’en a besoin.

Passez compact=1 pour omettre les données volumineuses des sujets, groupes, groupes parents, adhésions, réactions, tags et traductions associés. Les enregistrements principaux et les enregistrements associés nécessaires à l’interprétation de leur contenu restent présents.

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

Pour un contrôle précis, passez 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 s’appliquent aux enregistrements associés, pas à la ressource principale demandée au point de terminaison.

Les réponses contenant une collection incluent meta.total lorsqu’une taille exacte de la collection est définie. Le total est calculé avant l’application de limit et offset. Les points de terminaison, comme la recherche, qui renvoient volontairement un ensemble limité de résultats omettent meta.total plutôt que de renvoyer null.

Récapitulatif des points de terminaison

Groupes

Lister les groupes

Renvoie les groupes dans lesquels l’utilisateur associé à la clé API a une adhésion active.

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, y compris les groupes dont l’abonnement n’est pas actuellement actif. Vérifiez le champ enabled lorsqu’une intégration doit fonctionner uniquement avec les groupes activés.

Les principaux champs des groupes sont les suivants :

La réponse peut inclure des paramètres supplémentaires du groupe, des enregistrements de groupes parents associés 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 associé à la clé API.

GET /api/b2/groups/:id_or_key_or_handle

L’identifiant peut être l’identifiant numérique, la clé ou l’identifiant lisible du groupe.

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 et utilise les mêmes champs que le point de terminaison de liste. Une requête visant un groupe auquel l’utilisateur associé à la clé API ne peut pas accéder renvoie une erreur de permission.

Webhooks

L’API utilisateur fonctionne par requêtes : une intégration appelle Loomio lorsqu’elle souhaite lire ou modifier des données. Un webhook de groupe permet l’envoi dans l’autre sens. Loomio envoie les événements du groupe sélectionnés à votre point de terminaison au moment où ils se produisent ; une intégration n’a donc pas besoin d’interroger régulièrement l’API REST pour détecter les changements.

Les webhooks sont configurés par groupe et nécessitent la permission d’administrateur du groupe. Vous pouvez les gérer dans l’interface de 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 point de terminaison. Pour un point de terminaison à usage général, 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 et utilisez Tester la connexion pour envoyer un message de test.

Utilisez une destination HTTPS avec une URL impossible à deviner. Loomio exige que la destination se résolve en une adresse publique et bloque les requêtes vers des adresses de réseau locales ou privées.

Les agents et les autres intégrations peuvent aussi gérer les webhooks via les points de terminaison des chatbots décrits ci-dessous, avec une authentification Bearer. La ressource porte le nom chatbots pour assurer la compatibilité avec les intégrations de chat de Loomio, mais elle représente également les webhooks sortants à usage général.

Lister les webhooks

Renvoie les intégrations de chat configurées pour un groupe. L’utilisateur associé à la clé API doit être administrateur de ce groupe. La réponse inclut les URL de destination et 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

L’utilisateur associé à la clé API doit être administrateur du groupe désigné par group_id. Avant son enregistrement, la destination est vérifiée pour confirmer qu’il s’agit d’une URL publique.

Mettre à jour un webhook

PATCH /api/b2/chatbots/:id

Envoyez les champs à modifier. Le webhook ne peut pas être transféré à un autre groupe en modifiant 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

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 Loomio.

Types d’événements

Un webhook peut s’abonner aux types d’événements suivants :

Le webhook appartient à un seul groupe et reçoit les événements de ce groupe auxquels il est abonné. Les personnes peuvent 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 un succès. Les services qui reçoivent les webhooks doivent répondre rapidement, effectuer les traitements plus longs de manière asynchrone et accepter les envois en double ou dans le désordre.

Loomio n’ajoute actuellement 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 identifiant d’accès, ne l’exposez pas publiquement et incluez un jeton impossible à deviner dans l’URL lorsque le service destinataire le permet. Si vous avez besoin d’un schéma d’événements stable et lisible par machine ou d’un envoi signé, utilisez le webhook comme notification de changement et récupérez les enregistrements actuels via l’API utilisateur authentifiée.

Formats des données envoyées

Les données envoyées par les webhooks sont des messages destinés à être affichés dans des services de chat. Ce ne sont pas des enregistrements Loomio sérialisés complets. Les liens dans le message identifient le contenu Loomio concerné ; une intégration peut ensuite utiliser l’API utilisateur lorsqu’elle a besoin de l’état actuel sous une forme structurée.

Par exemple, le format Markdown général envoie un corps de requête 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 paramètre limitant le message au titre de la notification et de la version de Loomio. Les services destinataires doivent s’appuyer sur les champs de premier niveau documentés du format sélectionné plutôt que d’analyser la formulation des phrases.

Recherche

Recherchez les discussions, commentaires, sondages, votes et conclusions visibles par l’utilisateur associé à la clé API. Les résultats incluent le contenu public même si l’utilisateur n’est pas membre du groupe concerné ; le contenu privé reste soumis aux règles habituelles de visibilité des fils.

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 identifie l’enregistrement correspondant et son contexte visible avec des champs comprenant searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at et tags. Les champs qui ne s’appliquent pas à un résultat ont la valeur null.

Rapport de participation

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

GET /api/b2/reports

Paramètres

Une personne est déléguée lorsqu’elle dispose d’une adhésion active avec le rôle de délégué dans au moins un groupe sélectionné. Ses décomptes sont agrégés sur l’ensemble des groupes sélectionnés. Les lignes des délégués sont renvoyées même lorsque tous les décomptes d’activité sont nuls. Les décomptes couvrent les fils, commentaires, sondages, votes, conclusions et réactions ; ce ne sont pas des taux de participation aux votes. Les lignes des utilisateurs incluent aussi les bulletins de vote nominatifs attribués, déposés et non déposés. Les sondages anonymes sont exclus de tous les décomptes de vote par personne. all_votes_cast vaut true uniquement lorsqu’au moins un bulletin a été attribué et que tous les bulletins attribués ont été déposés.

L’API applique les mêmes règles de visibilité des groupes que le rapport dans l’application. Une clé de l’API utilisateur ne peut pas exposer les données de rapport de groupes auxquels cet utilisateur 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 au nom de l’utilisateur 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, un entier, ou de sa clé, 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 l’utilisateur de la clé API. Pour un groupe visible publiquement, une personne qui n’en est pas membre peut lister ses discussions publiques ; les discussions privées restent réservées aux utilisateurs qui peuvent les lire dans Loomio.

GET /api/b2/discussions

Paramètres

Compatibilité avec les anciennes versions : per et from sont acceptés comme alias de limit et offset et continueront à fonctionner.

Exemple

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

Lister les fils

Listez les fils de discussion et les fils de sondage visibles par l’utilisateur de la clé API, classés par activité la plus récente. 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

Lisez un fil, son flux d’événements ordonné ou son document Markdown visible complet.

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 le flux d’événements ordonné, comprenant les commentaires, sondages, votes et conclusions visibles. Le point de terminaison markdown renvoie l’intégralité du contenu visible du fil dans un seul document Markdown. Les raisons des votes ne sont incluses que lorsqu’elles sont visibles par l’utilisateur de la clé API.

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

Modifier une discussion

Modifiez une discussion en tant qu’utilisateur de 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 de manière logique

Supprimez une discussion de manière logique en tant qu’utilisateur associé à la clé API. Cette opération retire la discussion tout en conservant son enregistrement.

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 en tant qu’utilisateur 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 en tant qu’utilisateur 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 de manière logique

Supprimez un commentaire de manière logique en tant qu’utilisateur associé à la clé API. Cette opération retire le commentaire et masque son corps tout en conservant son enregistrement.

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 en tant qu’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

Afficher un sondage

Récupérez un sondage à l’aide de son identifiant, un entier, ou de sa clé, 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 par l’utilisateur de la clé API. Pour un groupe visible publiquement, une personne qui n’en est pas membre peut lister ses sondages publics ; les sondages privés restent réservés aux utilisateurs qui peuvent 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é avec les anciens paramètres : per et from sont acceptés comme alias de limit et offset et continueront à fonctionner.

Exemple

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

Modifier un sondage

Modifiez un sondage en tant qu’utilisateur de la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier ce 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 en tant qu’utilisateur de la clé API. Cette opération retire le sondage tout en conservant son enregistrement.

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

Liste les adhésions visibles par l’utilisateur de la clé API. Les membres du groupe peuvent consulter les noms, les identifiants, les titres et les rôles des membres. Les adresses e-mail sont incluses uniquement pour le compte de l’utilisateur de la clé API ou lorsque cet utilisateur 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. Toutes les nouvelles adresses e-mail recevront une invitation à rejoindre le groupe. Contrairement à la consultation de la liste 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 transmettez remove_absent=1, tous les membres du groupe qui ne figurent pas dans la liste seront retirés du groupe. Faites attention, 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

Cette opération renvoie un objet contenant {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.