> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/getting-started.md). # Bien démarrer avec l'API Envoyez votre premier retour via l'API en cinq minutes. L'API BAI Analytics fait une seule tâche et la fait bien : elle transfère les retours entre vos systèmes et vos Groupes de feedback. Vous envoyez les retours, la plateforme les analyse exactement comme s'ils étaient arrivés via un questionnaire ou un import, et vous récupérez ensuite les résultats (ou laissez un webhook vous indiquer quand ils sont prêts). Tout fonctionne en HTTPS via l'hôte d'ingestion public : ``` https://boundaryai-ingest-279197672085.europe-west9.run.app ``` {% hint style="warning" %} Utilisez cet hôte, pas l'adresse du tableau de bord. L'hôte du tableau de bord (`app.*`) sert l'application web et répond à chaque `/api/...` chemin avec une page HTML et un HTTP 200, qu'un client généré interprétera volontiers comme un corps de succès. La référence d'API publiée utilise le même hôte pour chaque opération. {% endhint %} Ce guide passe de zéro à des retours analysés. Il utilise le vocabulaire recommandé (`feedback_group` / `source` / `champ`) ; voir [Concepts et nomenclature](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/concepts-and-naming.md) pour voir comment cela se traduit dans l'application. *** ### Étape 1 : Créez une clé API Dans le tableau de bord, ouvrez **Intégrations**, allez dans **Outils de développement → Clés API** (réservé aux administrateurs), puis créez une clé. Choisissez une portée d'autorisation et copiez le secret : il ressemble à `inpk_live_...` et n'est affiché qu'une seule fois. Transmettez-la à chaque appel : ``` Authorization: Bearer inpk_live_... ``` Vérifiez que cela fonctionne : ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/me \\ -H "Authorization: Bearer $BAI_API_KEY" ``` `GET /me` renvoie les autorisations de votre clé, l'organisation à laquelle elle appartient (`org_name`), vos limites de débit effectives, l'état d'utilisation de l'organisation et les événements webhook auxquels vous pouvez vous abonner. Détails dans [Authentification et clés API](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/authentication.md). ### Étape 2 : Créez un groupe de feedback et une source Un **groupe de feedback** est le conteneur du projet ; une **source** source est un flux de retours à l'intérieur, avec des **champs**. `all` clé ; la création et la publication des sources nécessitent `create` ou `all`. Si votre groupe existe déjà, ignorez le premier appel et utilisez son identifiant. ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/feedback_groups/create \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{"name": "Support client UE"}' curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/create \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{ "feedback_group_id": "1842", "source_title": "Tickets d'assistance (synchronisation CRM)", "feedback_type": "support_ticket", "fields": [ {"field_title": "Quel était le problème ?", "field_type": "DEPTH_TEXT"}, {"field_title": "Quelle est la probabilité que vous nous recommandiez ?", "field_type": "NPS"} ] }' ``` Les sources sont créées en mode brouillon. Publiez-les pour commencer l'envoi : ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/publish \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{"source_id": 9021, "feedback_group_id": 1842}' ``` ### Étape 3 : Envoyez des retours ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/feedback/push \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -H "Idempotency-Key: 2c1f7c9e-batch-0712" \\ -d '{ "feedback_group_id": "1842", "source_id": "9021", "field": { "field_id": "31245", "content": [ "Le nouveau tableau de bord est excellent, mais les exports sont lents.", {"text": "L'assistance a résolu mon problème en un seul appel.", "external_id": "ticket-58121", "rating": 5, "occurred_at": "2026-07-12T09:30:00Z"} ] } }' ``` Les éléments peuvent être de simples chaînes ou des objets structurés. Trois champs valent la peine d'être utilisés dès le premier jour : * **`external_id`**: votre identifiant stable pour l'élément. Lors d'un envoi réessayé avec un `external_id` élément déjà présent dans le champ, l'envoi est ignoré plutôt qu'écrit deux fois ; la réponse le signale sous `skipped_duplicates`. * **`occurred_at`**: quand le retour a réellement eu lieu. Cela rétrodate l'élément afin que les groupes suivis dans le temps le placent dans la bonne période. * **`Idempotency-Key`** en-tête : rend l'ensemble de la requête réessayable sans risque pendant 24 heures. Pour des reprises historiques, utilisez `POST /feedback/push/bulk` (de nombreux champs dans un seul appel ; asynchrone par défaut, avec un mode synchrone pour les petits lots) ou `POST /feedback/upload` avec un fichier CSV/XLSX. Voir [Envoi des retours](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/pushing-feedback.md). ### Étape 4 : Lisez l'analyse (ou laissez un webhook vous le signaler) L'analyse s'exécute automatiquement une fois le contenu arrivé. Récupérez-la : ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/analysis \\ -H "Authorization: Bearer $BAI_API_KEY" ``` Vous obtenez la répartition des sentiments, les thèmes et les correspondances de la surveillance personnalisée. Au lieu d'interroger en boucle, abonnez-vous à l' `analysis.completed` événement ; voir [Webhooks](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/webhooks.md). *** ### Conventions à connaître * **Réponses réussies**: aujourd'hui, une réponse 2xx transporte directement la charge utile, comme dans chaque exemple. Chaque 2xx porte aussi `Deprecation` et `Sunset` en-têtes : ils annoncent qu'après la date de sunset, les charges utiles de succès seront encapsulées sous la forme `{"data": {...}}`, exactement comme les schémas de la référence le déclarent déjà. Ils ne déprécient aucun endpoint. Lire la charge utile à partir de `data` lorsque cette clé est présente, et depuis la racine sinon, permet à un client de rester correct des deux côtés du changement. * **Enveloppe d'erreur**: les échecs renvoient `{"error": {"code": "...", "message": "..."}}` (plus un `details` objet facultatif) avec un `code`. * **Limites de débit**: 60 requêtes/minute par clé et 300/minute par organisation par défaut, sur des fenêtres fixes de 60 secondes ; les réponses 429 incluent un `Retry-After` en-tête. Les limites exactes de votre clé se trouvent dans `GET /me`. * **Pagination**: `GET /feedback` est basée sur un curseur (renvoyez `next_cursor` jusqu'à ce que `has_more` soit false) ; `GET /sources/list` prend `limit` (50 par défaut, 200 max) et `offset` et renvoie une `pagination` objet. * **Clés de test**: `inpk_test_...` les clés fonctionnent de la même façon mais sont destinées aux intégrations de préproduction ; tenez-les à l'écart du trafic de production. {% hint style="success" %} Tout ce que vous envoyez participe pleinement au produit : les moniteurs de groupe avec couverture automatique surveillent automatiquement les sources API ([Surveillance personnalisée](/boundaryai-docs/boundaryai-docs-fr/analyser-vos-retours/custom-monitoring.md)), et les données API apparaissent dans les thèmes groupés, les périodes d'évolution et les rapports comme n'importe quelle autre source. {% endhint %} *** ### Aller plus loin * [Envoi des retours](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/pushing-feedback.md): reprises historiques en masse, import de fichiers, déduplication, anté-datation, effacement. * [Envoi d'invitations (API e-mail)](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/sending-invites.md): déclenchez des invitations personnalisées à des questionnaires depuis votre propre workflow. * [Webhooks](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/webhooks.md): agissez sur les événements au lieu d'interroger en boucle. * [Connecter des assistants IA (MCP)](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/mcp.md): laissez un assistant interroger les résultats. ### Ce qui n'est volontairement pas dans l'API Certaines choses sont volontairement réservées au tableau de bord, donc si vous cherchez un endpoint qui n'existe pas, c'est probablement pour cette raison : * **Création de questionnaires et de modèles**: ce que voient les répondants et les invités est conçu, prévisualisé et relu dans la plateforme ; l'API le déclenche mais ne peut pas le modifier. Une clé divulguée ne pourra jamais changer ce que vos clients reçoivent. * **Gestion des abonnements aux webhooks**: la création des abonnements et la lecture des secrets de signature se font dans le tableau de bord, donc une clé API ne peut pas rediriger votre flux d'événements vers une nouvelle URL. * **Configuration d'envoi d'e-mails**: les domaines d'envoi et les niveaux d'envoi sont des paramètres de l'organisation ([Paramètres](/boundaryai-docs/boundaryai-docs-fr/compte-et-administration/updating-settings.md#email-sending)); l'API envoie *par* leur intermédiaire, mais ne peut pas les modifier. * **Membres et paramètres de l'organisation**: les actions d'administration restent aux administrateurs. Si votre cas d'usage a réellement besoin de l'un de ces éléments par programme, dites-le-nous à ; nous préférons entendre votre besoin plutôt que de vous voir contourner la plateforme pour cela.