RAG sur Confluence avec n8n : construire un chatbot qui interroge votre base de connaissances

Confluence est souvent le seul endroit où une entreprise consigne ses décisions, ses procédures internes et l'historique de ses choix techniques — et c'est aussi l'un des outils où l'information est la plus difficile à retrouver une fois l'espace passé la centaine de pages. La recherche native fonctionne par mots-clés : elle retrouve une page si vous devinez le bon terme, pas si vous posez une vraie question comme « quelle est notre procédure de rotation des clés API ? ». Le RAG (retrieval-augmented generation) comble cet écart en récupérant les passages pertinents d'un corpus avant de les fournir à un modèle de langage au moment de répondre — l'approche a été formalisée par Lewis et al. dans un article présenté à NeurIPS en 2020, « Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks », qui montre que l'ancrage des réponses dans des documents récupérés améliore la factualité et permet de citer une source vérifiable. Voici comment construire ce pipeline avec n8n, de l'extraction des pages Confluence jusqu'à la synchronisation incrémentale.

Architecture du pipeline

1. Extraction : l'API REST Confluence liste les pages d'un ou plusieurs espaces et récupère leur contenu.
2. Conversion : le format storage (XHTML avec macros) de chaque page est transformé en texte exploitable.
3. Chunking : le texte est découpé en s'appuyant sur les titres de section de la page.
4. Vectorisation : chaque chunk devient un embedding, inséré dans Supabase pgvector avec ses métadonnées (espace, titre, URL).
5. Synchronisation : un workflow planifié interroge les pages modifiées via une requête CQL et ne réindexe qu'elles.

Si vous avez déjà lu nos guides sur le RAG avec Notion ou le RAG avec SharePoint, le squelette est identique — seules l'API source et ses pièges spécifiques changent : ici, l'absence de node natif, le format storage à base de macros, et la recherche CQL.

Étape 1 : authentification et extraction via l'API Confluence

n8n n'a pas de node Confluence officiel. Il existe des community nodes (n8n-nodes-confluence-cloud, @bitovi/n8n-nodes-confluence), mais pour un pipeline d'indexation qui doit gérer la pagination, les filtres CQL et le choix du format de corps de page, le node HTTP Request appelant directement l'API REST Confluence Cloud (v2) donne un contrôle plus fin et évite une dépendance externe.

Créez d'abord un compte de service Confluence, restreint en lecture seule aux espaces à indexer, puis générez un jeton API sur id.atlassian.com/manage-profile/security/api-tokens. Ce jeton, combiné à l'adresse email du compte, s'utilise en authentification Basic Auth — un credential HTTP Basic Auth dans n8n suffit. Notre guide pour sécuriser les credentials API dans n8n détaille comment restreindre et faire tourner ce type de jeton.

Deux appels suffisent à parcourir un espace :

GET https://{votre-domaine}.atlassian.net/wiki/api/v2/spaces?keys={SPACE_KEY}
→ renvoie l'id numérique de l'espace

GET https://{votre-domaine}.atlassian.net/wiki/api/v2/spaces/{id}/pages?body-format=storage&limit=250
→ liste les pages de l'espace, corps de page inclus

Par défaut, l'API v2 ne renvoie pas le corps des pages : le paramètre body-format=storage doit être explicitement demandé, sinon vous ne récupérez que les titres. La pagination se fait par curseur : tant que la réponse contient un champ _links.next, une exécution supplémentaire du node HTTP Request (dans une boucle Loop Over Items) va chercher la page suivante.

Étape 2 : convertir le format storage en texte exploitable

Le format storage de Confluence est du XHTML enrichi de macros propriétaires : une macro d'extrait de code s'écrit <ac:structured-macro ac:name="code">, un encart d'information <ac:structured-macro ac:name="info">, une section repliable <ac:structured-macro ac:name="expand">. Un node Code fait la conversion vers un texte structuré :

const html = $json.body.storage.value;
const text = html
  .replace(/<ac:structured-macro ac:name="(code|info|warning|note|expand)"[^>]*>[\s\S]*?<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>[\s\S]*?<\/ac:structured-macro>/g, '\n$2\n')
  .replace(/<h([1-6])[^>]*>(.*?)<\/h\1>/g, (_, lvl, t) => `\n${'#'.repeat(+lvl)} ${t}\n`)
  .replace(/<\/?(p|li)[^>]*>/g, '\n')
  .replace(/<[^>]+>/g, '')
  .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
  .replace(/\n{3,}/g, '\n\n')
  .trim();
return [{ json: { markdown: text } }];

Cette version simplifiée extrait le contenu utile des macros les plus fréquentes plutôt que de le perdre, et conserve les niveaux de titre — indispensable pour l'étape suivante. Si votre espace contient beaucoup de tableaux ou de macros imbriquées, complétez les règles au cas par cas : mieux vaut un chunk légèrement bruité qu'un paragraphe entier disparu silencieusement dans une macro non reconnue.

Étape 3 : un chunking guidé par les titres de page

Comme pour un espace Notion, une page Confluence bien rédigée porte déjà sa propre structure sémantique dans ses titres (h1 à h3). Découpez en priorité sur ces frontières, et gardez le contenu d'une section expand rattaché au titre sous lequel elle apparaît plutôt que de l'isoler dans son propre chunk. Les règles générales — taille de 500 à 1 000 tokens, chevauchement, découpe de secours au niveau du paragraphe quand une section dépasse la taille cible — sont détaillées dans notre guide du chunking de documents pour le RAG.

Étape 4 : embeddings, pgvector et métadonnées

Le node Supabase Vector Store (mode insert), branché à un modèle d'embeddings, vectorise et insère chaque chunk — la mise en place de la table documents et de la fonction de similarité est décrite dans notre guide RAG avec n8n et Supabase, et le choix du modèle dans notre comparatif des modèles d'embeddings. Si l'authentification Supabase elle-même n'est pas encore en place, notre guide pour connecter n8n à Supabase couvre la configuration du credential.

Les métadonnées à conserver pour chaque chunk :

{
  "confluence_page_id": "{{ $json.id }}",
  "space_key": "{{ $json.spaceId }}",
  "title": "{{ $json.title }}",
  "url": "{{ $json._links.base }}{{ $json._links.webui }}",
  "version": "{{ $json.version.number }}",
  "last_modified": "{{ $json.version.createdAt }}"
}

L'url, reconstruite à partir de _links.base et _links.webui, permet au chatbot de citer la page Confluence source avec un lien cliquable ; le confluence_page_id rend possible la suppression ciblée des anciens chunks à la resynchronisation ; version.number sert d'audit léger sur les révisions.

Étape 5 : synchronisation incrémentale avec CQL

Réindexer un espace entier à chaque exécution gaspille des appels API et des embeddings, surtout sur un espace de plusieurs centaines de pages. La bonne approche : interroger uniquement les pages modifiées depuis la dernière synchronisation, via la recherche CQL (Confluence Query Language) — une fonctionnalité qui vit encore sur l'API v1 de recherche, GET /wiki/rest/api/content/search?cql=..., même si le reste du pipeline utilise l'API v2 :

cql = space = "{SPACE_KEY}" AND type = "page" AND lastmodified >= "{{ $json.lastSyncedAt }}"

Un Schedule Trigger exécute cette requête à intervalle régulier (toutes les heures ou chaque nuit selon le rythme de mise à jour de l'espace), et pour chaque page renvoyée applique la séquence delete puis insert : suppression de tous les vecteurs portant son confluence_page_id, puis réinsertion des chunks fraîchement générés. Sans cette séquence, les versions obsolètes s'accumulent et le chatbot finit par citer une procédure qui n'est plus en vigueur — le pattern complet, suppressions de pages incluses, est détaillé dans notre guide sur la mise à jour d'un index RAG.

Le piège transversal : le quota par points

L'API Confluence Cloud n'applique pas une limite fixe en requêtes par seconde mais un quota par points : chaque appel consomme un coût variable selon le volume de données renvoyé, une page avec un corps volumineux coûtant plus cher qu'un simple listing de titres. Au-delà du quota, l'API répond 429 avec un en-tête Retry-After à respecter avant de réémettre la requête. En pratique : activez le retry on fail avec délai sur les nodes HTTP Request, traitez les pages en séquence plutôt qu'en parallèle lors de l'indexation initiale, et réservez body-format=storage aux appels qui en ont réellement besoin.

Interroger : agent, citations, et la suite

Côté interrogation, c'est un RAG standard : un AI Agent équipé du Vector Store en outil, avec un prompt qui impose de citer la ou les pages sources via l'URL stockée en métadonnée. Si vos utilisateurs cherchent souvent des termes exacts — noms de projets, identifiants internes, acronymes propres à l'entreprise — ajoutez une recherche hybride vecteurs + mots-clés, le raffinement au meilleur rapport effort/impact sur ce type de corpus. Alavi et Leidner le formulaient déjà en 2001 dans leur article fondateur sur les systèmes de gestion des connaissances, « Knowledge Management and Knowledge Management Systems: Conceptual Foundations and Research Issues » (MIS Quarterly, 2001) : la valeur d'un système de connaissances ne tient pas au volume stocké, mais à la facilité de le retrouver et de le réappliquer — exactement ce qu'un RAG bien construit ajoute à un espace Confluence déjà rempli. Le Pack Assistant RAG (119 €) regroupe la moitié aval prête à brancher — chatbot avec citations, API question-réponse, base vectorielle Supabase — sur laquelle greffer la synchronisation Confluence de cet article.

En résumé

• Extraction : pas de node Confluence natif — le node HTTP Request sur l'API v2 (spaces/{id}/pages?body-format=storage) offre le meilleur contrôle, avec pagination par curseur _links.next. Sans ce paramètre explicite, l'API ne renvoie que les titres, sans message d'erreur pour le signaler.
• Conversion : le format storage est du XHTML avec macros (ac:structured-macro) — un node Code doit les déballer plutôt que les ignorer, en conservant les niveaux de titre. Une macro non reconnue fait sinon disparaître silencieusement un paragraphe entier.
• Chunking : suivez la structure de titres de la page plutôt qu'un découpage sémantique coûteux.
• Métadonnées : confluence_page_id, url (reconstruite depuis _links.webui), version.number — pour les citations et la resynchronisation propre.
• Sync incrémentale : filtre lastmodified en CQL (API v1 de recherche), séquence delete puis insert, sur un compte de service dédié en lecture seule plutôt que le jeton d'un compte personnel.
• Quota : coût par points selon le volume de données renvoyé, pas un plafond fixe en requêtes par seconde ; respectez l'en-tête Retry-After.