Documentation de l'API

L'API BoundaryAI vous permet d'envoyer (push) des données de feedback par programmation, de créer des sources de données et de gérer le flux de collecte de feedback de votre organisation.

Aperçu

L'API BoundaryAI vous permet d'importer par programmation des données de feedback depuis n'importe quelle source – tickets de support, exports CRM, sondages, logs de chat – et de tirer parti de l'analyse par IA pour extraire des insights.

Concepts Fondamentaux

Avant de commencer, comprenez ces concepts clés :

Concept	Description
Feedback Group (Groupe de Feedback)	Un conteneur qui organise les sources de données liées (ex : "Feedback Client T1 2024").
Data Source (Source de Données)	Une collection de feedback au sein d'un groupe (ex : "Tickets Zendesk", "Sondage NPS").
Question	Un champ au sein d'une source de données qui contient le texte du feedback.
APS	Points d'Analyse (Analysis Points) – crédits consommés lors de l'envoi de contenu pour l'analyse par IA.

Export to Sheets

Comment ça marche

1. Créer un Groupe de Feedback (ou utiliser un existant) ↓

2. Créer une Source de Données avec des Questions ↓

3. Publier la Source de Données ↓

4. Envoyer (Push) votre contenu de feedback ↓

5. BoundaryAI analyse et extrait des insights

---

Authentification

Clés API

Toutes les requêtes API nécessitent une clé API passée dans l'en-tête Authorization : Authorization: Bearer inpk_live_abc123xyz_SbcEpUl9DWuI8IOI-YImkxPNSisaAab7t0goFuliM-4

Format de la Clé

inpk_{environment}_{key_id}_{secret}

• inpk : Préfixe fixe (Input API Key)

• environment : live (production) ou test (pas de déduction d'APS)

• key_id : Identifiant unique de 10 caractères

• secret : Secret encodé en Base64 (44 caractères)

Permissions de la Clé

Lors de la création d'une clé API, vous choisissez son niveau de permission :

• push

  • Envoyer du contenu vers des sources de données existantes

  • Scripts d'import automatisés

• create

  • Créer des groupes de feedback et des sources de données

  • Configuration de l'automatisation

• all

  • Tout

  • Contrôle programmatique complet

Obtenir votre Clé API

1. Allez dans Intégrations → API dans votre tableau de bord BoundaryAI

2. Cliquez sur Create API Key (Créer une clé API)

3. Choisissez un nom, un environnement et un niveau de permission

4. Sauvegardez la clé immédiatement — elle ne s'affichera qu'une seule fois !

Notes de Sécurité

• Les clés sont hachées côté serveur ; nous ne stockons jamais le texte brut.

• Utilisez des clés d'environnement de test pendant le développement (pas de frais APS).

• Faites une rotation régulière des clés via le tableau de bord.

• Ne commitez jamais de clés dans le contrôle de version (Git, etc.).

---

Faire des Requêtes

URLs de Base

• Europe : https://app.boundary-ai.com/

• Amérique du Nord : https://app.boundary-ai.com/

• APAC : Bientôt disponible

Format de Requête

Toutes les requêtes doivent inclure les en-têtes appropriés.

Limitation de Débit (Rate Limiting)

Trois couches protègent l'API :

1. Par Clé : 60/min (configurable) - Clé API individuelle

2. Par Org : 300/min - Toutes les clés de l'organisation

3. Par IP : 600/min - Protection de secours

En-têtes de réponse : En cas de limitation, vous recevrez une réponse HTTP 429 avec un en-tête Retry-After.

Idempotence

Empêchez les données en double en incluant une clé d'idempotence :

• Première requête : S'exécute normalement, met la réponse en cache pour 24h.

• Même clé + même payload : Renvoie la réponse en cache (pas d'insertion en double).

• Même clé + payload différent : Renvoie une erreur de conflit HTTP 409.

Bonne pratique : Utilisez un identifiant unique comme {source}-{date}-{batch} pour chaque lot d'importation.

---

Référence des Endpoints

Référence Rapide

Méthode	Endpoint	Description	Perm.
GET	/api/input/surveys/list	Lister tous les groupes & sources de données	any
POST	/api/input/survey_series/create	Créer un groupe de feedback	create
POST	/api/input/survey/create	Créer une source de données	create
POST	/api/input/survey/publish	Publier une source de données	create
POST	/api/input/content/push	Envoyer du contenu vers une question	push
POST	/api/input/content/push/bulk	Envoyer du contenu vers plusieurs questions	push

Export to Sheets

Lister les Sources de Données (List Data Sources)

Récupérez tous les groupes de feedback et sources de données auxquels votre clé API peut accéder. Exécutez ceci en premier pour obtenir les ID nécessaires à l'envoi de contenu.

Paramètres de requête (Query Parameters)

• survey_series_id (integer) : Filtrer sur un groupe spécifique

• survey_id (integer) : Filtrer sur une source de données spécifique

Comprendre la Réponse

• survey_series : Tableau de groupes de feedback

• surveys : Tableau de sources de données au sein d'un groupe

• questions : Champs disponibles pour le contenu

• accepts_text : Important ! N'envoyez du texte qu'aux questions où ceci est true.

• mode : ACCESSIBLE = publié, EDITING = brouillon

Envoyer du Contenu (Push Content)

Envoyez du texte de feedback à une question spécifique. C'est l'endpoint principal pour importer des données.

Corps de la Requête (Request Body)

• survey_series_id (string, Requis) : ID du groupe de feedback

• survey_id (string, Requis) : ID de la source de données

• question.question_id (string, Requis) : ID de la question (doit avoir accepts_text: true)

• question.content (array, Requis) : Tableau de chaînes de caractères (feedback)

• source_reference (string, Non requis) : Votre référence pour ce lot d'import

Limites de Contenu

• Max éléments par requête : 1 000

• Max caractères par élément : 10 000

Réponse

• inserted : Nombre de nouvelles entrées ajoutées

• duplicates : Nombre d'entrées en double ignorées

• aps_deducted : Points d'analyse consommés

Envoi Groupé (Bulk Push Content)

Envoyez du contenu à plusieurs questions en une seule requête. Utile lorsque vos données comportent plusieurs champs.

Corps de la Requête

• survey_series_id (string, Requis)

• survey_id (string, Requis)

• questions (array, Requis) : Tableau d'objets questions (max 100)

  • questions[].question_id (string, Requis)

  • questions[].content (array, Requis)

• source_reference (string, Non requis)

Créer un Groupe de Feedback (Create Feedback Group)

Créez un nouveau groupe pour organiser les sources de données liées. Permission Requise : create ou all

Paramètres

• name (string, Requis) : Nom du groupe (2-255 caractères)

Note : Si un groupe avec le même nom existe, il renvoie le groupe existant avec "created": false.

Créer une Source de Données (Create Data Source)

Créez une nouvelle source de données avec des questions au sein d'un groupe. Permission Requise : create ou all

Paramètres

• survey_series_id (string, Requis) : ID du groupe parent

• survey_title (string, Requis) : Nom de la source (1-100 car.)

• survey_description (string, Non requis) : Description

• questions (array, Non requis) : Tableau de questions à créer

Types de Questions

Type	Code	Description	Analysé par IA ?
DEPTH_TEXT	long_answer	Texte long (Analysé par IA)	✅ Oui
TEXT	short_answer	Texte court	✅ Oui
MCQ	mcq	Choix multiple	❌ Non
SCQ	scq	Choix unique	❌ Non
RATING	rating	Échelle 1-5	❌ Non
NPS	nps	Net Promoter Score (0-10)	❌ Non

Export to Sheets

Astuce : Utilisez DEPTH_TEXT pour le texte de feedback que vous souhaitez faire analyser par l'IA.

Publier une Source de Données (Publish Data Source)

Publiez une source de données pour activer la collecte de données et l'analyse. Permission Requise : create ou all

Corps de la Requête

JSON

{
  "survey_series_id": 123,
  "survey_id": 456
}

Note : Vous devez publier une source de données avant de pouvoir y envoyer du contenu.

---

Webhooks

Voir la page Webhooks.

---

Exemple Complet

Voici un flux de travail complet : créer un groupe, ajouter une source de données, la publier et envoyer du contenu.

Bash

# Étape 1 : Créer un Groupe de Feedback (Série)
echo "Création du groupe..."
SERIES_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/survey_series/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Q1 2024 Feedback Client\"}")

SERIES_ID=$(echo $SERIES_RESPONSE | jq -r '.survey_series.id')
echo "ID du groupe créé : $SERIES_ID"

# Étape 2 : Créer une Source de Données avec une question
echo "Création de la source de données..."
SURVEY_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/survey/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"survey_series_id\": \"$SERIES_ID\",
    \"survey_title\": \"Import Zendesk\",
    \"questions\": [
      {\"question_title\": \"Contenu du Ticket\", \"question_type\": \"DEPTH_TEXT\"}
    ]
  }")

SURVEY_ID=$(echo $SURVEY_RESPONSE | jq -r '.survey_id')
QUESTION_ID=$(echo $SURVEY_RESPONSE | jq -r '.questions[0].id')
echo "ID de la source créée : $SURVEY_ID, ID de la question : $QUESTION_ID"

# Étape 3 : Publier la source de données
echo "Publication de la source de données..."
curl -s -X POST "$BASE_URL/api/input/survey/publish" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"survey_series_id\": $SERIES_ID, \"survey_id\": $SURVEY_ID}"

# Étape 4 : Envoyer (Push) le contenu du feedback
echo "Envoi du contenu..."
PUSH_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/content/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zendesk-batch-$(date +%Y%m%d)-001" \
  -d "{
    \"survey_series_id\": \"$SERIES_ID\",
    \"survey_id\": \"$SURVEY_ID\",
    \"question\": {
      \"question_id\": \"$QUESTION_ID\",
      \"content\": [
        \"Le processus de paiement était confus et j'ai abandonné\",
        \"J'adore la nouvelle fonction de recherche - tellement plus rapide !\",
        \"L'application plante chaque fois que j'essaie d'uploader un PDF\",
        \"Le support client a résolu mon problème en une heure\",
        \"Ce serait génial d'avoir une option mode sombre\"
      ]
    },
    \"source_reference\": \"zendesk-export-2024-01-15\"
  }")

echo "Résultat de l'envoi : $PUSH_RESPONSE"
echo ""
echo "Terminé ! Visualisez votre feedback dans le tableau de bord BoundaryAI."

Support

• Email : [e-mail]

• Documentation : docs.boundary-ai.com

• Tableau de bord : app.boundary-ai.com