Connecteurs API

Plutôt que de copier vos données dans une base de connaissance, vous pouvez laisser l’IA interroger votre API en direct. Vous enregistrez une connexion (URL + authentification + opérations), et chaque opération en lecture devient un outil que le modèle peut appeler dans sa réflexion, comme la recherche web ou le RAG agentique.

Un service qui expose un serveur MCP se branche sans déclarer d’opérations

Si le service (Notion, Linear, un outil maison) propose un serveur MCP, déclarez-le plutôt comme serveur MCP : il annonce lui-même ses outils, et il n’y a aucune opération à décrire à la main. Un connecteur API reste le bon choix pour une API HTTP sans serveur MCP, ou pour synchroniser les données dans une base de connaissance.

Lecture ET écriture

Vous décidez : une opération de lecture (read) ou d’écriture (write — création, mise à jour, suppression). Enregistrer une opération write vaut autorisation : l’IA pourra l’exécuter sur vos systèmes (le modèle est prévenu qu’elle modifie des données). N’ajoutez que les opérations que vous acceptez de voir l’IA déclencher, et restreignez l’accès par clé si besoin.

1. Créer une connexion

Au portail (Intégrations → Connecteurs API) ou via l’API. Une connexion porte :

• un nom et une URL de base (https://…) ;
• une authentification : none, api_key (header ou query), bearer, basic, ou oauth2 (Google Drive et tout autre fournisseur OAuth2 — cf. section dédiée ci-dessous ; une bibliothèque SharePoint se branche, elle, sur l’application Microsoft de votre organisation, sans rien à saisir : cf. Synchroniser une bibliothèque SharePoint). Le secret est chiffré au repos (AES-256-GCM, une clé dédiée par connexion) ;
• des headers statiques optionnels (auth_config.headers), envoyés sur chaque requête — typiquement une version d’API imposée par le fournisseur, ex. Notion : "auth_config": { "headers": { "Notion-Version": "2022-06-28" } }. Jamais de secret ici : ces headers ne sont pas chiffrés (et voyagent dans l’export du connecteur) ; les headers Authorization et Cookie y sont refusés, le secret passe par credential ;
• une liste d’opérations définies à la main.

curl https://api.miraca.fr/v1/connections \
  -H "Authorization: Bearer $MIRACA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon Airtable",
    "base_url": "https://api.airtable.com",
    "auth_type": "bearer",
    "credential": "patXXXX.XXXX",
    "operations": [
      {
        "name": "list_records",
        "description": "Liste les enregistrements d une table.",
        "method": "GET",
        "path": "/v0/{base_id}/{table}",
        "params": [
          { "name": "base_id", "in": "path", "type": "string", "required": true },
          { "name": "table",   "in": "path", "type": "string", "required": true },
          { "name": "filterByFormula", "in": "query", "type": "string" }
        ],
        "access": "read"
      }
    ]
  }'

La réponse renvoie le slug de la connexion (identifiant stable par compte) — c’est lui qui sert à l’activer dans une requête de chat. Le secret n’est jamais renvoyé.

Anatomie d’une opération

Champ	Rôle
name	nom de l’opération → suffixe de l’outil exposé au modèle (<slug>__<opération>).
description	(optionnel) contexte d’usage injecté dans la déf d’outil — aide fortement le modèle à savoir quand/comment l’appeler.
method	GET, POST… (une lecture peut être un POST, ex. une requête de recherche).
path	gabarit relatif à base_url ; les {param} sont substitués depuis les arguments. Peut aussi être une URL ABSOLUE (https://…) — elle court-circuite alors base_url pour cette opération précise. Utile quand un même jeu de credentials (ex. les mêmes tokens OAuth2) couvre plusieurs hôtes d’API — cf. l’exemple Google Docs ci-dessous.
params	liste typée. in ∈ path | query | body ; type ∈ string | integer | number | boolean ; required.
access	read (défaut) | write. Les deux sont exécutées ; write ajoute un marqueur « modifie des données » à la déf, et n’est appelable que par une clé qui a l’accès en lecture et écriture (voir Permissions).
examples	(optionnel) tableau JSON d’exemples d’appel ([{…args…}]) → une « bibliothèque » que le modèle peut imiter.

Au niveau de la connexion, un champ doc_url (optionnel) pointe vers la doc de l’API : il est ajouté au contexte des outils, et l’IA peut le lire via web_fetch si la recherche web est active.

Lire un fichier (PDF, Word, Excel)

Une opération peut rendre un fichier plutôt que du JSON. Le contenu est alors extrait automatiquement avant d’arriver au modèle : un classeur devient un tableau par feuille, un document Word et un PDF deviennent du texte. Aucun réglage à poser — la reconnaissance se fait sur la réponse elle-même.

Formats extraits : PDF, DOCX, XLSX. Un fichier d’un autre format binaire (image, archive, vidéo) est signalé comme illisible plutôt que rendu en caractères inintelligibles ; les formats Office d’avant 2007 (.doc, .xls) sont refusés avec la marche à suivre (les convertir).

Le document est aussi déposé dans l’espace de travail de la conversation : aux questions suivantes, il est relu sur place au lieu d’être retéléchargé, et un fichier trop long pour tenir dans une réponse y reste lisible en entier.

Exemple, pour un fichier importé dans Google Drive (un .xlsx envoyé depuis un ordinateur, par opposition à un Google Sheets natif) :

{
  "name": "download-file",
  "method": "GET",
  "path": "/files/{fileId}?alt=media",
  "access": "read",
  "description": "Télécharge le contenu d'un fichier IMPORTÉ (xlsx, pdf, docx…). Pour un Google Docs/Sheets/Slides NATIF, utilisez export-file.",
  "params": [
    { "name": "fileId", "in": "path", "type": "string", "required": true },
    { "name": "supportsAllDrives", "in": "query", "type": "boolean" }
  ]
}

Le ?alt=media est écrit dans le gabarit de chemin, donc figé : sans lui, la même URL rend les métadonnées du fichier au lieu de son contenu, et rien ne le signalerait. Tout paramètre qui décide de la nature de la réponse gagne à être posé là plutôt que laissé au modèle.

Une opération de téléchargement et une opération d’export ne se remplacent pas

Chez Google, export ne fonctionne que sur les documents natifs (Docs, Sheets, Slides) et refuse les fichiers importés ; alt=media fait l’inverse. Déclarez les deux : le modèle choisit d’après le type du fichier, qu’il lit dans la liste.

Authentification OAuth2

Certains fournisseurs (Google Drive en premier lieu) exigent OAuth2 plutôt qu’un secret statique. Le mécanisme est générique (réutilisable pour tout fournisseur OAuth2) — Google n’est qu’un préréglage.

Qui peut connecter, et sous quel compte

Connecter un connecteur demande un rôle de propriétaire, d’administrateur ou de contributeur dans l’organisation qui le possède. Les jetons ne sont enregistrés que sous la session Miraca de la personne qui a cliqué sur Connecter : si, au retour du fournisseur, le navigateur n’est pas connecté à Miraca, la page de connexion s’affiche puis l’enregistrement se termine ; s’il est connecté à un autre compte Miraca, rien n’est enregistré et un message le dit.

Pas d’app Google publiée par Miraca

Miraca ne publie pas d’app Google multi-tenant (ça exigerait un audit CASA annuel récurrent pour un seul fournisseur). Vous créez votre propre app OAuth Internal dans votre Google Workspace — réservée aux comptes Workspace (un @gmail.com personnel n’est pas supporté, il exigerait une app publiée/vérifiée par Google).

Créer l’app côté Google (une fois, dans la console Google Cloud de votre Workspace) :

1. Créez un projet, puis un écran de consentement OAuth de type Interne (« Internal ») — pas besoin de vérification Google, aucun plafond d’utilisateurs, refresh token de durée normale.
2. Activez sur le projet les quatre API que le connecteur appelle : Google Drive, Google Docs, Google Sheets et Google Slides. Une API non activée répond 403 SERVICE_DISABLED à chaque opération de son format (lecture d’un tableur, écriture d’un document), alors que l’exploration du Drive fonctionne.
3. Créez des identifiants OAuth client ID (type « Application Web »), et déclarez cette entrée dans URI de redirection autorisés (le portail l’affiche et la copie pour vous) :

   https://app.miraca.fr/api/integrations/oauth/callback

   Attention au champ : c’est bien URI de redirection autorisés, et non « Origines JavaScript autorisées », juste au-dessus dans la même page. La correspondance est stricte au caractère près (pas de slash final), et Google met parfois quelques minutes à propager un ajout.
4. Notez le Client ID et le Client secret générés.

Vous aviez déclaré app.astrolabe.chat ?

Miraca s’appelait Astrolabe, et son adresse de retour était https://app.astrolabe.chat/api/integrations/oauth/callback. Une application déclarée à cette époque continue de fonctionner sans rien changer : elle garde cette adresse, et le portail la lui affiche encore quand vous l’ouvrez. Tout ce que vous déclarez aujourd’hui utilise app.miraca.fr.

Dans tous les cas, déclarez chez le fournisseur l’adresse que le portail affiche pour l’application concernée : une autre donne Error 400: redirect_uri_mismatch au moment du consentement.

Créer la connexion côté Miraca (portail, auth_type: "oauth2") :

{
  "name": "Google Drive",
  "base_url": "https://www.googleapis.com/drive/v3",
  "auth_type": "oauth2",
  "auth_config": {
    "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_url": "https://oauth2.googleapis.com/token",
    "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
    // quirk Google : force l'émission d'un refresh_token à CHAQUE consentement
    "extra_authorize_params": { "access_type": "offline", "prompt": "consent" }
  },
  "credential": { "client_id": "…", "client_secret": "…" },
  "operations": [
    {
      "name": "list_files",
      "method": "GET",
      "path": "/files",
      "access": "read",
      "params": [
        { "name": "q", "in": "query", "type": "string" },
        { "name": "pageSize", "in": "query", "type": "integer" },
        { "name": "pageToken", "in": "query", "type": "string" },
        { "name": "fields", "in": "query", "type": "string" }
      ]
    }
  ]
}

Le param q scope l’opération à un dossier précis, ex. "'<folder_id>' in parents" (fixé en paramètre fixe de la config de synchronisation, cf. section suivante) — sans lui, list_files liste tout le Drive accessible à l’app.

Au portail, cliquez ensuite « Connecter » sur la carte du connecteur : vous êtes redirigé vers l’écran de consentement Google, puis ramené au portail une fois l’autorisation accordée. La finalisation du consentement (l’échange du code contre les tokens) se fait uniquement au portail — un navigateur est nécessaire, ce n’est pas exposé sur /v1. La création de la connexion (avec client_id/client_secret), elle, reste possible via l’API.

Le consentement se lance depuis la page Intégrations et se termine sous la session Miraca de la personne qui l’a demandé (voir la note « Qui peut connecter, et sous quel compte », plus haut) : le navigateur du retour n’a pas à être celui du départ. Si le retour affiche « Session expirée, réessayez. », la demande a expiré (elle vaut dix minutes) : relancez-la avec « Connecter ».

Restreindre l’accès à certains dossiers : un compte Google DÉDIÉ, pas un filtre

Le scope OAuth drive donne accès à tout ce que le compte Google autorisé peut voir — il n’y a pas de notion de « dossiers autorisés » côté Google pour ce type de connexion. Le paramètre q d’une synchronisation (cf. « Technique générale » plus haut, section Paramètres fixes) ne filtre que ce qui est indexé dans la base de connaissance — il ne restreint pas ce qu’un agent peut voir s’il utilise le connecteur en direct dans le chat (tools_enabled: ["connection:<slug>"]) : dans ce mode, c’est le modèle qui choisit les arguments de list_files, y compris sans q.

Pour une véritable frontière de sécurité (« cette connexion ne doit voir QUE ces dossiers, en toute circonstance »), utilisez un compte Google dédié :

1. Créez un compte Google Workspace dédié (compte « de service », pas un utilisateur réel), auquel rien n’est partagé par défaut.
2. Partagez explicitement avec ce compte uniquement les dossiers à exposer à Miraca (partage nominatif par email — jamais « n’importe qui avec le lien »).
3. Effectuez le consentement OAuth (« Connecter ») en étant connecté à Google en tant que ce compte (une fenêtre de navigation privée force le sélecteur de compte plutôt que de réutiliser une session déjà ouverte).

Le token obtenu ne peut alors littéralement rien voir en dehors de ce qui a été partagé avec ce compte — vérifié côté Google, pas par une config Miraca qu’un agent pourrait contourner. Révoquer un partage plus tard suffit à couper l’accès, sans toucher à la connexion. (Un compte dédié nécessite généralement une licence Workspace comme tout utilisateur — à vérifier auprès de votre administrateur selon votre configuration.)

Un même connecteur, plusieurs hôtes d’API — ex. lire/écrire un Google Doc

L’API Google Drive (base_url du connecteur) ne gère QUE les métadonnées d’un fichier (nom, dossier, corbeille) — jamais son contenu. Écrire du texte dans un Google Doc natif passe par l’API Google Docs, qui vit sur un hôte différent (docs.googleapis.com au lieu de www.googleapis.com). Comme les mêmes tokens OAuth2 couvrent les deux (scopes drive et documents demandés ensemble), une seule connexion peut déclarer une opération sur cet autre hôte : donnez-lui un path absolu (https://docs.googleapis.com/…) au lieu d’un chemin relatif — il court-circuite base_url pour cette opération précise, le reste de la connexion (auth, autres opérations) est inchangé.

{
  "name": "write_doc_text",
  "method": "POST",
  "path": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
  "access": "write",
  "params": [
    { "name": "documentId", "in": "path", "type": "string", "required": true },
    { "name": "requests", "in": "body", "type": "array", "required": true }
  ]
}

Le même principe s’applique à toute famille d’API partageant un jeu de credentials sur des hôtes différents (ex. Google Sheets sur sheets.googleapis.com).

Les modèles du menu « Nouveau connecteur »

Le menu « Nouveau connecteur » propose des modèles prêts à l’emploi : l’URL, les opérations, la description et le descriptif sont déjà remplis, il reste à coller votre jeton. Chaque modèle est vérifié contre la documentation officielle de son API.

Modèle	Ce qu’il couvre	À préparer
Airtable	Lecture et écriture des enregistrements, découverte des bases, des tables et des champs	Jeton d’accès personnel avec data.records:read, data.records:write et schema.bases:read, accordé à chaque base
GitHub	Un dépôt en lecture seule : code, arborescence, historique, issues et pull requests	Jeton en lecture sur le dépôt ; remplacer PROPRIETAIRE/DEPOT aux quatre endroits indiqués
Google Drive	Fichiers du Drive, contenu des Docs, Sheets et Slides, en lecture et écriture	Application OAuth (ci-dessus), avec les quatre API activées
HubSpot	Objets du CRM, recherche, pipelines, propriétaires, associations, en lecture et écriture	Jeton pat- : clé de service, ou application privée déjà créée, avec les droits crm.objects.* voulus
Notion	Pages, bases de données et blocs partagés avec l’intégration, en lecture et écriture	Jeton d’intégration ; partager les pages et bases concernées avec elle
Pennylane	Factures clients et fournisseurs, clients, fournisseurs, produits, transactions	Jeton de l’API externe v2
Pipedrive	Deals, personnes, organisations, activités, pipelines, en lecture et écriture	Jeton d’API personnel ; remplacer VOTRE-DOMAINE par votre sous-domaine
Stripe	Paiements, clients, factures, abonnements, solde, virements, en lecture seule	Clé restreinte en lecture seule, de préférence à la clé secrète

Deux choses à savoir :

• Notion : le modèle parle la version 2022-06-28 de l’API. Une base à laquelle Notion a ajouté une seconde source de données n’y est plus lue ; l’assistant le signale au lieu de conclure que la base n’existe pas.
• Un connecteur est une copie de son modèle : il ne suit pas ses évolutions. Quand nous corrigeons un modèle, la correction est aussi appliquée aux connecteurs dont les opérations ou le descriptif sont restés identiques au modèle ; ce que vous avez retouché reste le vôtre.

Google Analytics (mesure d’audience GA4)

Le modèle Google Analytics du menu « Nouveau connecteur » branche une propriété GA4 en lecture seule : l’assistant peut alors répondre à « quelles pages ont été les plus vues le mois dernier ? », « d’où vient le trafic ? » ou « combien de visites cette semaine par rapport à la précédente ? ». Il repose sur l’OAuth2 décrit ci-dessus, avec la même application Interne de votre Google Workspace.

1. Dans le projet Google Cloud de votre application OAuth, activez deux API : Google Analytics Data API (les rapports) et Google Analytics Admin API (la liste des propriétés). Sans elles, chaque appel est refusé (403, « API has not been used in project »).
2. Relevez l’identifiant de la propriété dans Google Analytics : Administration, puis Détails de la propriété. C’est un nombre (312345678), pas l’identifiant de mesure G-XXXX.
3. Au portail, choisissez le modèle, puis remplacez ID_PROPRIETE par ce nombre à quatre endroits : le chemin des opérations rapport, rapport-temps-reel et lire-metadonnees, et la description. Saisissez le Client ID et le Client secret.
4. Cliquez « Connecter » en étant identifié à Google avec un compte qui a au moins le rôle Lecteur sur la propriété.

Opération	Ce qu’elle rend
rapport	les métriques d’une période, ventilées par dimensions (pages, sources, pays, appareils, dates), avec tri, filtres et comparaison de deux périodes
rapport-temps-reel	l’activité des 30 dernières minutes
lire-metadonnees	toutes les dimensions et métriques de la propriété, personnalisées comprises
lister-proprietes	les comptes et propriétés visibles par le compte connecté

Ce qu’il faut savoir

• Une propriété par connecteur. L’identifiant est figé dans le chemin : pour un second site, créez un second connecteur à partir du même modèle.
• Un seul consentement pour l’organisation. Le connecteur lit ce que voit le compte Google qui l’a branché, et toutes les personnes qui ont accès au connecteur obtiennent les mêmes chiffres.
• Aucune écriture. Le scope demandé est analytics.readonly ; un rapport se demande par POST chez Google, mais il ne modifie rien et ne passe donc par aucune confirmation.
• Des écarts avec l’interface de Google sont normaux : les données du jour sont partielles, et Google masque les petites valeurs (seuils de confidentialité) ou échantillonne les gros volumes.
• Quotas de Google : chaque propriété dispose d’un quota de jetons par heure et par jour. Une question courante en consomme très peu ; un message 429 signale qu’il est épuisé.

2. Utiliser la connexion dans le chat

Activez-la avec tools_enabled, en référençant son slug préfixé par connection: :

curl https://api.miraca.fr/v1/chat/completions \
  -H "Authorization: Bearer $MIRACA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large",
    "messages": [{ "role": "user", "content": "Combien d enregistrements dans la table Clients ?" }],
    "tools_enabled": ["connection:mon-airtable"]
  }'

Toutes les opérations de la connexion sont alors proposées au modèle, qui choisit lesquelles appeler. Les connecteurs coexistent avec la recherche web et le RAG agentique dans la même réflexion : tools_enabled: ["web_search", "connection:mon-airtable"] + knowledge_base.

Une réponse volumineuse (8 000 caractères ou plus) est rendue au modèle dans la limite de la place qui reste dans sa fenêtre, et gardée en entier dans l’espace de travail quand la requête en a un (une discussion de l’assistant, ou le paramètre workspace) : le modèle la relit par morceaux ou la traite dans un script, au lieu de rappeler l’API. Cette copie de travail est effacée 24 heures après la dernière activité (cf. Espaces de travail).

Activer une opération précise (moins de tokens)

Pour n’exposer qu’une opération (au lieu de toutes), suffixez le slug par : + le nom de l’opération : tools_enabled: ["connection:mon-airtable:list_records"]. Seule cette déf d’outil est injectée — utile pour les automatisations (Make/n8n) qui savent ce qu’elles veulent, et pour réduire le contexte (donc le coût) sur les connecteurs riches en opérations.

3. Permissions

Deux niveaux :

• Scope de clé connections : une clé API doit porter ce scope pour utiliser le moindre connecteur (choisi à la création/édition de la clé). Sans lui, les connecteurs ne sont pas proposés au modèle.

• Accès par connexion : par défaut, toutes vos clés peuvent utiliser un nouveau connecteur (toutes ses opérations, lecture comme écriture). Au portail (menu Accès du connecteur), vous réglez un niveau pour toutes les clés du compte, puis clé par clé :

  Niveau	Ce que la clé peut appeler
  Aucun accès	Rien : le connecteur ne lui est pas proposé.
  Lecture seule	Les opérations read. Une opération write est refusée.
  Lecture et écriture	Toutes les opérations.

  Une clé a le plus élevé des deux niveaux : le sien et celui de toutes les clés. Vous pouvez donc laisser tout le compte en lecture seule et n’ouvrir l’écriture qu’à une clé. Le niveau vaut partout où la clé sert : agent (/v1/chat/completions), exécution de code et serveur MCP.

Connecteurs restreints avant l’arrivée des niveaux (octobre 2026)

Les clés autorisées une à une l’étaient en lecture seule, et le serveur MCP les laissait pourtant appeler les opérations d’écriture. Ce n’est plus le cas : pour qu’une de ces clés écrive, passez-la en « Lecture et écriture » dans le menu Accès du connecteur.

Gérer les connexions (API)

Méthode	Route	Rôle
GET	/v1/connections	liste
POST	/v1/connections	créer
GET	/v1/connections/{slug}	détail
PATCH	/v1/connections/{slug}	modifier (credential omis = inchangé)
DELETE	/v1/connections/{slug}	supprimer
POST	/v1/connections/{slug}/sync	déclencher une synchronisation → { ok, outcome }

Toutes ces routes exigent le scope connections. Le POST .../sync lance la synchronisation configurée (cf. section suivante) et facture l’embedding sur la clé de l’appel — c’est la parité API du bouton « Synchroniser » du portail (en plus de la planification automatique).

Synchroniser une connexion vers une base de connaissance

Pour rendre les données d’un connecteur cherchables, la voie recommandée est de les synchroniser dans une base de connaissance : Miraca aspire les enregistrements d’une opération de liste et les enregistre comme documents de la base (un enregistrement = un document, clé d’upsert = external_id). La recherche reste alors unifiée sur la base — même pertinence, mêmes facettes, et surtout la recherche sémantique — pour n’importe quel connecteur, y compris ceux dont l’API n’offre aucune recherche texte.

Deux rôles complémentaires d’un connecteur

• Outil de l’agent (ci-dessus) : l’IA interroge votre API en direct, pour une question ponctuelle et une donnée toujours fraîche.
• Synchronisé vers une base (ici) : pour la recherche documentaire (sémantique + facettes) sur un volume d’enregistrements. La donnée est copiée (chiffrée au repos) et rafraîchie à chaque synchronisation.

Dans la modale du connecteur, section Synchronisation :

1. Opération de liste : une opération read qui liste les enregistrements. Miraca pagine automatiquement, à condition que l’opération déclare le paramètre de pagination de l’API (cf. Pagination suivie plus bas).

2. Paramètres fixes (optionnel) : arguments requis par l’opération en plus de la pagination. Cas typique — une base Airtable dont la table est un paramètre (GET /{table}) : mettez {"table":"Entreprises"}. Une synchronisation cible une source ; pour plusieurs tables, créez une config (ou un connecteur) par table.

   Technique générale : scoper une synchronisation à un sous-ensemble

   Les paramètres fixes sont le mécanisme générique pour restreindre une synchronisation à une partie seulement d’une source — le même principe s’applique à tout connecteur :

   • Airtable : {"table":"Entreprises"} (une table).
   • Google Drive : {"q": "'<ID_DU_DOSSIER>' in parents and trashed = false"} (un dossier — cf. l’exemple complet plus bas). Combinable avec un filtre de type pour ne cibler qu’un seul format Google dans ce dossier, ex. uniquement les Sheets : {"q": "'<ID_DU_DOSSIER>' in parents and mimeType='application/vnd.google-apps.spreadsheet' and trashed = false"} (remplacez par application/vnd.google-apps.document pour les Docs, ...presentation pour les Slides — cf. le schema du modèle Drive pour la liste complète des mimeType).
   • Notion : l’opération /search couvre TOUT le workspace et ne peut pas être scopée. Pour synchroniser une seule base de données, ajoutez au connecteur une opération dédiée POST /databases/{database_id}/query (mêmes objets « page » en retour, tous les helpers Notion s’appliquent pareil), puis pointez la sync dessus avec {"database_id": "<ID_DE_LA_BASE_NOTION>"} en paramètres fixes.

   Une seule opération de liste par sync : pour plusieurs sous-ensembles (plusieurs tables, dossiers, bases ou formats), créez une config de sync (ou un connecteur) par sous-ensemble.

   Cette opération doit être déclarée en lecture (access: "read"). La synchronisation la rappelle page après page, à chaque passage : configurée sur une opération d’écriture, elle est refusée, à l’enregistrement comme au lancement, et rien n’est envoyé au système connecté. Le verbe ne compte pas : une liste qui se demande par POST et que vous déclarez en lecture se synchronise.

   Docs/Sheets/Slides pris individuellement (get_doc/write_sheet_values/write_presentation…, cf. l’exemple Google Docs ci-dessous) n’ont pas de notion de « dossier » à scoper : ce sont des opérations sur un seul fichier, adressé par son id (obtenu via list_files, éventuellement scopé comme ci-dessus). Le scoping concerne la liste, pas la lecture/écriture d’un fichier précis une fois son id connu.

3. Base cible : le slug de la base de connaissance qui reçoit les documents.

4. Correspondance des champs (map) : comment transformer un enregistrement en document. Cliquez Détecter pour pré-remplir identifiant / titre / date / lien / version à partir d’un échantillon de l’opération (ajustez ensuite ; les facettes restent à définir car elles dépendent de votre base). Chaque champ est un nom de champ (top-level, chemin pointé, ou fields.X façon Airtable) ou un gabarit {champ} composant plusieurs champs.

   • external_id (requis) — l’identifiant stable de l’enregistrement (clé d’upsert) ;
   • title (requis) — le titre du document ;
   • text (optionnel) — le contenu indexé ; par défaut, tous les champs de l’enregistrement sont sérialisés en lignes « Clé : valeur » (bon pour le sémantique) ;
   • date (optionnel) — la date métier du document (doc_date) ;
   • url (optionnel) — un lien vers l’enregistrement, ex. https://airtable.com/appXXX/{id} ;
   • facets (optionnel) — une correspondance clé de facette → champ, pour filtrer ensuite ;
   • version (optionnel) — un champ de date de modification (ex. updated_at) : un document n’est ré-indexé que si cette valeur change → synchronisations incrémentales peu coûteuses, insensibles aux champs volatils (liens signés, etc.). Sinon, la détection se base sur le contenu.

   Notion : géré automatiquement

   Chez Notion, le titre et les données ne sont pas des champs à plat : ils vivent dans properties (structure imbriquée, nom de colonne variable). Miraca le reconnaît tout seul : « Détecter » pose le bon titre + last_edited_time comme version, et le texte indexé aplatit les propriétés en clair (Nom : … · Rôle : … · Statut : …, chaque type de propriété rendu proprement). Vous n’avez rien à mapper à la main. Le corps des pages est aussi indexé : Miraca va chercher les blocs de chaque page (paragraphes, titres, listes, tâches, tableaux…) et les ajoute au texte — donc les vraies pages de contenu, pas seulement les bases de données, deviennent interrogeables. (Le premier miroir complet est donc plus long — un appel par page ; les synchronisations suivantes ne rafraîchissent que les pages modifiées, repérées par last_edited_time. Les sous-pages sont indexées comme leurs propres documents, pas dupliquées dans le parent.) Le bruit est écarté automatiquement : les objets « base de données » et les pages archivées / à la corbeille ne sont pas indexés. Chaque page est aussi préfixée de son fil d’Ariane (Chemin : Espace › Base parente › …) : une ligne de base ou un item de checklist (« J’ai pris un café… ») n’a de sens que dans son contexte parent, indispensable à l’IA comme à la recherche. Le titre est enrichi du parent direct pour des sources lisibles. Enfin, deux métadonnées peuvent alimenter des facettes (si votre base les déclare) : createur (auteur Notion created_by, résolu en nom — présent sur toutes les pages) et date_creation (date de création, en YYYY-MM-DD). La date métier (date) est mappée par défaut sur la dernière modification (last_edited_time, plus utile pour la fraîcheur) ; le bruit (objets « base de données », pages archivées / à la corbeille) est écarté automatiquement.

   Google Drive : contenu couvert automatiquement

   Pour un connecteur Drive, title/date/url/facettes se mappent normalement sur les champs de métadonnées (name, modifiedTime, webViewLink, mimeType…) — le bouton Détecter les propose. Le texte indexé, lui, dépend du type de fichier :

   • Docs/Sheets/Slides natifs Google → export automatique en texte/CSV ;
   • fichiers uploadés (PDF, DOCX, XLSX, TXT, MD, CSV, HTML, RTF…) → téléchargés et extraits (même extracteur que les pièces jointes du chat) ;
   • autres formats (images, vidéos, archives…) → indexés en métadonnées seules (titre, date, lien, facettes), sans contenu textuel.

   Les fichiers à la corbeille et les dossiers ne sont jamais synchronisés (réconciliés à la corbeille → purgés au run suivant).

5. Découpage : simple (déterministe, gratuit, bon défaut pour des enregistrements courts), whole (un enregistrement = un extrait : le plus juste quand chaque fiche synchronisée est déjà une unité complète, contact ou facture) ou ai (un modèle re-segmente le document selon l’intention de la base et remplit les facettes, utile pour des documents longs ou quand la base a des facettes à extraire). En mode ai, choisissez le modèle de découpage et la clé qui porte la consommation. Sans choix explicite, c’est la dernière clé API créée sur le compte qui est retenue — les clés internes de Miraca (assistant, accès MCP d’une personne, copilote) n’entrent jamais dans ce choix. En mode ai, cette clé doit avoir la permission chat : sans elle, chaque document échoue et la synchronisation se termine en « terminée avec N erreurs ». L’embedding, lui, est toujours facturé sur cette clé. Si vous ne précisez pas de découpage, la synchronisation suit le réglage par défaut de la base cible.

6. Fréquence : manuelle (bouton uniquement) ou automatique — quotidienne, hebdomadaire ou mensuelle. Miraca resynchronise alors tout seul à cette cadence (vous pouvez toujours lancer une sync à la main entre deux).

Prévisualiser avant de lancer

Le bouton « Prévisualiser » (section Aperçu de la modale) applique la correspondance en cours aux 10 premiers documents et montre exactement ce qui serait indexé — titre, date, lien, facettes et texte (corps des pages Notion compris). Rien n’est écrit : c’est de la lecture seule, idéale pour vérifier un mapping (ex. un titre qui retombe sur l’identifiant signale un champ mal choisi) avant de synchroniser toute la source.

Cliquez Synchroniser : Miraca reflète l’état de la source dans la base (vraie synchronisation miroir) :

• ajouts / modifications → (ré)indexés par external_id. Un document n’est ré-embeddé que si son contenu a changé (empreinte) → les relances sont peu coûteuses ;
• suppressions → les documents de ce connecteur disparus de la source sont supprimés de la base (réconciliation). Garde-fou : si la source ne renvoie aucun enregistrement (auth cassée, mauvaise config), rien n’est supprimé : le miroir n’est jamais vidé par erreur. Rien n’est supprimé non plus tant que la liste n’a pas été lue en entier (cf. « Liste incomplète » ci-dessous) : un document absent d’une liste partielle n’a pas forcément disparu.

Seuls les documents issus de ce connecteur sont concernés : vos documents ajoutés à la main ou synchronisés depuis une autre source ne sont jamais touchés. La synchronisation est gratuite hormis l’embedding des documents (re)indexés (facturé sur la clé choisie).

« Terminée avec N erreurs » n’est pas un succès

Un enregistrement qui échoue (facette refusée, texte illisible, clé sans la permission chat en découpage ai) n’interrompt pas la synchronisation : les autres continuent. La sync se termine alors en « terminée avec N erreurs » — N est le nombre réel d’enregistrements en échec, et le portail affiche la première cause. Un N élevé avec 0 (ré)indexé signale une cause commune (le plus souvent la clé) : la base cible ne reçoit plus rien tant qu’elle n’est pas corrigée. En API, POST /v1/connections/{slug}/sync renvoie error_count (le compte) et errors (un échantillon des messages).

Pagination suivie par la synchronisation

Une API rend une longue liste par pages. La synchronisation demande des pages de 100 enregistrements (quand l’opération a un paramètre de taille : limit, pageSize, per_page, maxRecords) et suit la liste jusqu’au bout, si l’opération déclare le paramètre qui porte la page suivante, ou si la réponse donne elle-même l’adresse de la page suivante. Les formes reconnues :

Ce que l’API renvoie	Paramètre à déclarer dans l’opération	Exemples
un curseur au premier niveau de la réponse (offset, next, next_cursor, nextCursor, nextPageToken, cursor)	un paramètre dont le nom contient cursor, offset ou pageToken (cursor, start_cursor, offset, pageToken)	Airtable, Notion, Pennylane, Google
paging.next.after	after	HubSpot
has_more: true, sans curseur	starting_after (reçoit l’identifiant du dernier objet de la page)	Stripe, listes
has_more: true et next_page	page	Stripe, recherche
additional_data.next_cursor	cursor	Pipedrive v2
additional_data.pagination.next_start	start	Pipedrive v1
@odata.nextLink (l’adresse complète de la page suivante)	aucun : le lien est suivi tel quel, à condition de pointer vers l’hôte du connecteur	Microsoft Graph (SharePoint, OneDrive)

Un lien @odata.nextLink qui désigne un autre hôte que celui du connecteur n’est jamais suivi (le jeton ne part que vers cet hôte) : la synchronisation s’arrête avec une erreur, sans rien supprimer.

Deux plafonds bornent une synchronisation : 50 000 enregistrements et 600 pages.

Ne sont pas suivies : la pagination par numéro de page (page=2), la suite donnée dans un en-tête Link (GitHub), et le décalage numérique que la réponse ne renvoie pas (offset=100). Dans le dernier cas, la synchronisation s’arrête à la première page sans pouvoir le détecter : restreignez la liste avec les paramètres fixes pour qu’elle tienne en une page.

« Liste incomplète » : la base ne reflète qu’une partie de la source

Quand la synchronisation s’arrête en sachant qu’il reste des enregistrements, elle le dit au lieu de se présenter comme terminée :

• ce qui a été lu est indexé normalement ;
• la carte du connecteur affiche « liste incomplète » et la raison, et le restera tant que la cause n’est pas réglée (une synchronisation planifiée l’affiche de la même façon) ;
• aucune suppression n’est répercutée : un document absent d’une liste partielle peut très bien exister sur une page qui n’a pas été lue.

En API, le bilan porte incomplete : null si la liste a été lue en entier, sinon { "reason": "...", "message": "..." }, et reconciled vaut alors false.

reason	Ce qui s’est passé	Que faire
next_page_unreachable	l’API annonce une suite, et l’opération ne déclare pas le paramètre qui la demande	déclarer ce paramètre dans l’opération (tableau ci-dessus), puis relancer
full_page	la page est revenue pleine (100 enregistrements) et l’opération n’a aucun paramètre de pagination reconnu	déclarer le paramètre si l’API pagine par curseur, sinon restreindre la liste avec les paramètres fixes
stuck_cursor	l’API a redonné le curseur qui venait de lui être envoyé	vérifier que le paramètre déclaré est celui que l’API attend
limit_reached	un plafond (50 000 enregistrements ou 600 pages) a été atteint et la source en compte davantage	restreindre la liste avec les paramètres fixes, ou la répartir sur plusieurs connecteurs
provider_stopped	la liste a été lue, mais le système connecté a limité ou interrompu les appels pendant la lecture des contenus (bibliothèque SharePoint)	rien : la passe suivante reprend là où celle-ci s’est arrêtée

Une fois le paramètre déclaré, la synchronisation suivante lit la liste entière : tous les enregistrements qui n’étaient pas encore dans la base sont indexés à ce moment-là, et leur embedding est facturé sur la clé de la synchronisation.

La sync tourne en arrière-plan

Une synchronisation s’exécute comme un job de fond : elle continue même si vous quittez la page (et reprend automatiquement en cas de coupure serveur). La carte du connecteur affiche la progression en direct (« Synchronisation… 120/450 »), et un bouton Arrêter l’interrompt proprement (aucune suppression n’est alors appliquée). Les synchronisations planifiées (cron) tournent de la même façon et sont visibles au même endroit. (L’API POST /v1/connections/{slug}/sync, elle, reste synchrone et renvoie directement le bilan — pratique pour les scripts.)

Sur de gros volumes (des milliers d’enregistrements, ou une source lente/limitée en débit comme Notion), la sync tolère les lenteurs (délai d’attente rallongé + nouvelles tentatives automatiques sur erreur passagère) et reste reprenable : si un run n’aspire pas tout, relancez, les documents déjà indexés sont sautés et la sync repart là où elle en était.

// exemple de config `sync` (champ de la connexion, via l'API ou pré-rempli au portail)
{
  "operation": "list_records",   // une opération de LISTE déclarée en lecture
  "args": { "table": "Entreprises" },
  "target_kb": "crm-airtable",
  "map": {
    "external_id": "id",
    "title": "fields.Nom",
    "date": "fields.Créé le",
    "url": "https://airtable.com/appXXX/{id}",
    "facets": { "ville": "fields.Ville", "statut": "fields.Statut" }
  },
  "chunking": "ai",          // "simple" | "ai" | "whole" ; absent = défaut de la base cible
  "chunk_model": "mistral-large",  // (mode ai) modèle de découpage
  "chunk_size": 1000,        // (mode simple) taille cible des extraits, 200-6000
  "key": "<token de clé>",   // (optionnel) clé portant la conso ; défaut = dernière clé du compte
                             // (jamais une clé interne) ; le mode "ai" exige la permission `chat`
  "schedule": "daily"        // "manual" (défaut) | "daily" | "weekly" | "monthly"
}

Fraîcheur : une synchronisation planifiée (schedule) se rafraîchit une fois par jour / semaine / mois. Pour une donnée qui doit être à la seconde, préférez le connecteur comme outil de l’agent (interrogation en direct).

Synchroniser une bibliothèque SharePoint

Le modèle Microsoft SharePoint (bibliothèque de documents) du menu « Nouveau connecteur » copie les fichiers d’une bibliothèque de documents SharePoint (Microsoft 365) dans une base de connaissance et la tient à jour, par la synchronisation miroir décrite plus haut. L’assistant et l’API retrouvent ensuite ces documents, et les citent, comme ceux de n’importe quelle base. Le connecteur est en lecture seule : il ne modifie rien dans SharePoint.

Il n’y a rien à saisir pour l’authentification : le connecteur utilise l’application Microsoft de votre organisation, ou celle de Miraca. Pas de Client ID, pas de secret.

Avant de commencer

• Un Microsoft 365 de travail. Un compte Microsoft personnel (outlook.com) n’a pas de SharePoint et ne convient pas.
• Une application Microsoft utilisable par votre organisation. Miraca fournit la sienne, qui apparaît d’elle-même dans Portail › Intégrations › Applications OAuth ; vous pouvez aussi y déclarer la vôtre. Sans application utilisable, le connecteur ne se crée pas, et la fenêtre renvoie à cette section.
• L’approbation par l’administrateur de votre Microsoft 365. Le connecteur demande la lecture des fichiers et des sites (Files.Read.All, Sites.Read.All). Dans un Microsoft 365 aux réglages par défaut, il arrive qu’un utilisateur ne puisse pas les accorder seul : si Microsoft demande l’approbation d’un administrateur (erreur AADSTS90094), l’administrateur approuve l’application une fois, pour toute l’organisation. La page Compte connecté explique où trouver le lien d’approbation (section « Pour l’administrateur : Microsoft »). Si votre organisation a déclaré sa propre application, elle doit déclarer dans Microsoft Entra les autorisations déléguées Files.Read.All et Sites.Read.All.
• Un compte qui lit la bibliothèque. Le connecteur lit ce que lit le compte qui l’a connecté, et rien de plus. Un compte de service, auquel seule cette bibliothèque est partagée, vaut mieux qu’un compte nominatif.

Pas à pas

1. Créer le connecteur. Intégrations › Connecteurs API › Nouveau connecteur, puis le modèle Microsoft SharePoint (bibliothèque de documents). La section Authentification dit qu’il n’y a rien à saisir. Donnez un nom, et choisissez la base cible dans la section Source : c’est la base de connaissance qui recevra les documents. Cliquez sur Créer le connecteur.
2. Le connecter à Microsoft. Ouvrez le connecteur (clic sur sa carte, la mention « Autorisation Microsoft à terminer » le signale), puis Connecter à Microsoft, et connectez-vous avec le compte qui lit la bibliothèque. Vous revenez au portail une fois l’accès accordé, et la fenêtre indique Connecté.
3. Choisir la bibliothèque. Rouvrez le connecteur : la section Bibliothèque SharePoint propose le champ Adresse du site SharePoint. Collez l’adresse que montre votre navigateur, par exemple https://votre-organisation.sharepoint.com/sites/Equipe (celle d’une page ou d’une bibliothèque du site convient, ce qui suit le nom du site est ignoré), puis Trouver les bibliothèques. Cliquez sur celle à synchroniser : elle est posée dans les paramètres fixes de la synchronisation (drive_id).
4. Régler la fréquence, puis enregistrer. La fréquence est Manuelle au départ : choisissez-en une automatique (quotidienne, hebdomadaire, mensuelle) une fois la bibliothèque choisie. Cliquez sur Enregistrer.
5. Synchroniser. Sur la carte du connecteur, Synchroniser. La première synchronisation lit chaque fichier ; les suivantes ne reprennent que ceux qui ont changé.

Une bibliothèque par connecteur

Un connecteur synchronise une bibliothèque. Pour en lire une seconde, créez un second connecteur à partir du même modèle (vous pouvez les envoyer vers la même base : leurs documents ne se mélangent pas). Choisir une autre bibliothèque sur un connecteur déjà synchronisé remplace, à la prochaine synchronisation, les documents de la précédente dans la base.

Si Trouver les bibliothèques échoue, le message dit pourquoi :

Message	Ce qu’il faut faire
« Adresse de site non reconnue »	Collez l’adresse d’un site de la forme https://organisation.sharepoint.com/sites/NomDuSite (ou /teams/…). Le site racine de l’organisation et un sous-site ne se devinent pas de l’adresse.
« Aucun site SharePoint à cette adresse »	Vérifiez l’adresse. Le compte connecté ne voit peut-être pas ce site.
« Le compte Microsoft qui a connecté ce connecteur n’a pas accès à ce site… »	Donnez au compte un accès en lecture au site, ou faites approuver l’application par l’administrateur de votre Microsoft 365 (cf. plus haut).
« Microsoft a refusé le jeton du connecteur : reconnectez-le »	Reconnecter à Microsoft dans la fenêtre du connecteur.
« Microsoft limite temporairement les appels »	Patientez quelques instants et recommencez.

Ce qui est synchronisé

Chaque fichier de la bibliothèque, sous-dossiers compris, devient un document de la base. Son titre est le nom du fichier, sa date celle de sa dernière modification, et son lien renvoie vers le fichier dans SharePoint.

Le texte n’est lu que pour les formats que Miraca sait extraire, reconnus à l’extension du nom : PDF, Word (.docx), Excel (.xlsx), texte (.txt, .md, .markdown, .text, .log), tableaux (.csv, .tsv), pages web (.html, .htm) et .rtf. Tout autre fichier est indexé par ses métadonnées seules (nom, date, lien), sans contenu : images, archives, présentations (.pptx) et anciens formats Office (.doc, .xls) en font partie, de même qu’un PDF scanné qui ne contient aucun texte. Au plus 60 000 caractères de texte sont retenus par fichier.

Ne sont jamais synchronisés : les dossiers, les éléments supprimés, les carnets OneNote et les listes SharePoint (ce ne sont pas des fichiers). Un OneDrive personnel n’est pas l’objet de ce connecteur : chaque personne lit le sien en connectant son compte (page Compte connecté).

Le bouton Prévisualiser montre le nom, la date et le lien des dix premiers fichiers : leur texte n’est lu qu’à la synchronisation.

Quand un fichier change ou disparaît

La synchronisation est un miroir : la base reflète la bibliothèque telle que le compte connecté la lit.

• Un fichier ajouté est indexé ; un fichier modifié, renommé ou déplacé est relu et ré-indexé ; un fichier inchangé n’est pas relu et ne coûte aucun embedding.
• Un fichier supprimé de la bibliothèque, ou dont le compte connecté perd l’accès, disparaît de la base à la synchronisation suivante.
• Garde-fous : si Microsoft ne renvoie aucun fichier, si la synchronisation est arrêtée, ou si la lecture de la liste échoue en route, rien n’est supprimé. Une bibliothèque trop longue pour être lue en entier (plus de 50 000 éléments, dossiers compris, ou 600 pages) est indexée jusqu’au plafond : la carte affiche « liste incomplète » et aucune suppression n’est répercutée tant que c’est le cas (voir « Liste incomplète » plus haut). Si Microsoft limite les appels pendant la lecture des fichiers, la synchronisation s’arrête sans insister, la carte affiche « interrompue » avec le nombre de fichiers restants, et la passe suivante reprend.

Limites

• 15 Mo par fichier. Au-delà, le fichier est indexé par ses métadonnées seules, et la synchronisation se termine en « terminée avec N erreurs » en le nommant.
• Microsoft limite le débit des appels. Quand il demande d’attendre, Miraca attend le délai indiqué (deux minutes au plus). Au-delà, ou si Microsoft continue de refuser, la synchronisation s’arrête pour ne pas insister, sans rien supprimer de la base, et la suivante reprend où elle s’était arrêtée. Sur une grande bibliothèque, lancez la première synchronisation en dehors des heures de travail.
• Le connecteur tient à la personne qui l’a connecté. Si son compte est désactivé ou si Microsoft révoque ses accès, la synchronisation s’arrête avec un message qui demande de Reconnecter à Microsoft, et la carte du connecteur le propose. Rien n’est supprimé entre-temps.
• Retirer au compte son accès à la bibliothèque ne demande pas de reconnecter : la synchronisation échoue alors sur l’erreur d’accès que rend Microsoft, sans rien supprimer. Rendez l’accès dans SharePoint, puis relancez.

Les droits SharePoint ne sont pas reproduits

Les documents copiés dans la base sont lisibles par toute personne qui peut lire cette base dans Miraca, qu’elle ait ou non accès au fichier dans SharePoint. Choisissez une base dont l’accès correspond à la sensibilité de la bibliothèque, et un compte connecté qui ne lit que ce qui doit être indexé. Le texte extrait est enregistré chiffré au repos dans la base.

Les opérations du connecteur appelées en direct (chercher un site, lister une bibliothèque, chercher des fichiers) ne sont pas limitées à la bibliothèque choisie : qui peut appeler le connecteur parcourt les noms et les adresses de tout ce que lit le compte connecté. Or les propriétaires, les administrateurs et les contributeurs de votre organisation peuvent tous appeler ses connecteurs depuis l’assistant : le menu Accès ne règle que les clés API, et le partage ne concerne que les membres. Le vrai réglage est donc le compte Microsoft qui connecte le connecteur : choisissez un compte qui ne lit que ce que toute votre organisation peut voir, par exemple un compte de service limité aux sites concernés, et retirez l’accès aux clés qui n’en ont pas besoin.

Opérations du modèle

Le modèle déclare aussi des opérations en lecture seule, que l’assistant peut appeler en direct (tools_enabled: ["connection:<slug>"]) pour retrouver une bibliothèque ou un fichier. Pour répondre sur le texte des documents, la recherche dans la base synchronisée est la voie à privilégier.

Opération	Ce qu’elle rend
trouver-site	un site d’après le nom de son adresse (contoso.sharepoint.com, Equipe)
chercher-sites	les sites qui correspondent à un mot
lister-bibliotheques	les bibliothèques de documents d’un site (leur id est le drive_id)
lister-racine, lister-dossier	le contenu de la racine, ou d’un dossier, d’une bibliothèque
chercher-fichiers	les fichiers d’une bibliothèque qui correspondent à un mot
lister-fichiers	toute la bibliothèque, sous-dossiers compris : sert à la synchronisation

Une liste rendue en direct est paginée par Microsoft et n’est suivie que par la synchronisation : en direct, elle peut être partielle, et un total qu’on en tirerait serait faux.

Par l’API

La création par POST /v1/connections est possible sans le portail : auth_type vaut oauth2, auth_config porte {"application": "microsoft"} (et, au choix, une liste scopes de lecture), base_url est https://graph.microsoft.com/v1.0, et aucun credential n’est envoyé. La réponse porte "application": "microsoft". Le connecteur doit appartenir à une organisation qui a une application Microsoft utilisable. Seuls les scopes de lecture du modèle sont acceptés, et tout chemin d’opération qui sort de graph.microsoft.com est refusé : le jeton ne part pas ailleurs.

Le consentement reste réservé au portail (bouton Connecter à Microsoft), comme pour tout connecteur OAuth2. Pour reprendre les opérations du modèle, créez le connecteur au portail puis lisez-le par GET /v1/connections/{slug}. La bibliothèque se pose dans la configuration de synchronisation, sync.args valant {"drive_id": "<id de la bibliothèque>"} ; l’opération lister-bibliotheques en donne l’identifiant.

Exporter / importer une connexion

Une configuration de connecteur est portable : vous pouvez l’exporter pour la partager (avec un collègue, entre deux comptes, ou pour la versionner) puis la réimporter ailleurs.

• Exporter : sur la carte d’un connecteur, le bouton Exporter télécharge un fichier <slug>.connection.json. Il contient l’URL de base, le type d’auth, les opérations, la description, le schéma et la configuration de recherche, mais jamais le secret (clé/token). Pour oauth2, authorize_url/token_url/scopes (structurels) sont exportés, mais jamais client_id/client_secret ni les tokens obtenus. Un connecteur branché sur l’application Microsoft (bibliothèque SharePoint) s’exporte avec application: "microsoft", jamais l’identifiant d’une application : importé, il se rebranche sur l’application Microsoft de l’organisation qui l’importe. Côté API, un simple GET /v1/connections/{slug} renvoie la même configuration (le secret n’est jamais exposé).
• Importer : le bouton Importer (en haut de la section) lit un fichier .json et pré-remplit la modale de création. Comme le secret n’est jamais inclus dans un export, vous ressaisissez votre clé avant de créer le connecteur. Côté API, postez le fichier sur POST /v1/connections en ajoutant le champ credential.

Le format tolère aussi une configuration écrite à la main : seul base_url est obligatoire.

À savoir

• Non-streaming : comme tout mode agentique, la réponse arrive en une fois (stream: true ignoré).
• Gratuit : l’appel à votre API n’est pas facturé en plus (seuls les tokens du modèle le sont).
• Sécurité : les réponses de votre API sont traitées comme des données, jamais comme des instructions. Les réponses sont bornées, les redirections ne sont pas suivies, et une garde SSRF refuse les URL privées ou loopback, y compris lorsqu’elles sont désignées par un nom d’hôte qui résout vers une adresse privée, et pas seulement par une adresse écrite littéralement. La connexion est épinglée sur l’adresse vérifiée, de sorte qu’un nom ne peut pas changer de destination entre la vérification et l’appel. Un base_url (ou le path absolu d’une opération) écrit comme une adresse privée ou loopback (127.0.0.1, 10.…, 192.168.…, localhost) est refusé dès la création du connecteur, par une erreur 400 qui le dit ; un nom d’hôte qui résout vers un réseau interne est refusé au moment de l’appel.
• Souveraineté : une connexion vers votre API hébergée en UE garde les données dans un pipeline européen. Router vers un modèle cloud reste soumis à l’opt-in habituel.

Les écritures sont validées

Une opération déclarée en write modifie un système qui n’est pas le nôtre : elle est donc soumise à une validation humaine avant d’être exécutée par l’assistant ou par le Slackbot. Voir Confirmation des écritures pour ce qui est soumis, comment s’en dispenser, et ce qu’un administrateur peut imposer.

Les tâches programmées en sont exemptes : leur périmètre d’écriture se déclare à la création de la tâche.