Feedback API

Almirant expose une API REST publique (et non MCP) pour ingérer les retours provenant de widgets intégrés à des sites web ou d'intégrations de serveur à serveur. Cette API est indépendante du serveur MCP et ne nécessite pas de clé API Almirant.

Authentification

La Feedback API utilise un système d'authentification basé sur des Public Keys et des widget tokens :

• Public Key (pk_...) : identifie la source de retours. Elle est obtenue lors de la création d'une source de retours dans Almirant et peut être exposée sans risque dans le frontend.
• Widget Token : token signé temporaire obtenu via l'endpoint bootstrap. Sa durée est limitée et il sert à valider les requêtes d'ingestion.

Endpoints

GET /feedback/widget/bootstrap

Initialise le widget de retours. Renvoie la configuration de la source et un token signé temporaire nécessaire pour envoyer un retour.

Paramètres de requête :

Nom	Type	Obligatoire	Description
publicKey	string	Oui	Public Key de la source de retours (pk_...)

Exemple de requête :

curl "https://api.almirant.ai/feedback/widget/bootstrap?publicKey=pk_abc123def456"

Réponse réussie (200) :

{
  "success": true,
  "data": {
    "source": {
      "publicKey": "pk_abc123def456",
      "type": "widget",
      "name": "Web App Feedback"
    },
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "expiresAt": 1708531200,
    "config": {
      "requireCaptcha": true
    }
  }
}

Erreurs :

Code	Description
404	Source de retours introuvable pour la publicKey fournie
403	L'origine de la requête (domaine) ne figure pas dans la liste des domaines autorisés

---

POST /feedback/ingest

Envoie un élément de retour. Nécessite le token obtenu depuis l'endpoint bootstrap.

En-têtes :

Content-Type: application/json

Corps :

Nom	Type	Obligatoire	Description
publicKey	string	Oui	Public Key de la source de retours
token	string	Oui	Widget token obtenu depuis bootstrap
message	string	Oui	Contenu du retour (1 à 5000 caractères)
category	string	Non	Catégorie : bug, feature_request, improvement, question, praise, other
email	string	Non	E-mail de l'expéditeur
pageUrl	string	Non	URL de la page sur laquelle le retour a été envoyé
locale	string	Non	Langue/locale de l'utilisateur
captchaToken	string	Non	Token hCaptcha (requis si le captcha est activé pour la source)

Exemple de requête :

curl -X POST "https://api.almirant.ai/feedback/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "pk_abc123def456",
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "message": "The registration form does not validate emails correctly",
    "category": "bug",
    "email": "[email protected]",
    "pageUrl": "https://myapp.com/register",
    "locale": "en"
  }'

Réponse réussie (201) :

{
  "success": true,
  "data": {
    "id": "fb-uuid-001",
    "status": "new",
    "createdAt": "2025-02-15T10:30:00.000Z"
  }
}

Erreurs :

Code	Description
400	Token captcha non valide ou manquant (lorsque le captcha est requis)
401	Widget token non valide ou expiré
403	L'origine de la requête (domaine) n'est pas autorisée
404	Source de retours introuvable
409	Retour en double détecté (même contenu envoyé récemment)
429	Limite de débit dépassée

Flux d'intégration complet

1. Le widget se charge sur la page de l'utilisateur
   |
2. GET /feedback/widget/bootstrap?publicKey=pk_...
   |-- Obtient un token temporaire + la configuration
   |
3. L'utilisateur rédige et envoie son retour
   |
4. POST /feedback/ingest
   |-- publicKey + token + message + metadata
   |
5. Le retour apparaît dans Almirant comme nouvel élément

Protections

L'API inclut les protections suivantes :

• Validation de l'origine : accepte uniquement les requêtes provenant des domaines configurés dans la source de retours (prend en charge les wildcards comme *.mydomain.com)
• Widget tokens signés : tokens HMAC-SHA256 avec expiration basée sur le temps
• Limitation de débit : limite le nombre de requêtes par IP et par source dans une fenêtre temporelle
• Déduplication : détecte et rejette les retours en double envoyés récemment (sur la base du hash SHA-256 du contenu normalisé)
• hCaptcha : vérification captcha facultative par source (activée par défaut)

Catégories de retours

Catégorie	Description
bug	Rapport de bug ou de dysfonctionnement
feature_request	Demande de nouvelle fonctionnalité
improvement	Suggestion d'amélioration d'une fonctionnalité existante
question	Question ou demande d'information
praise	Retour positif
other	Catégorie par défaut lorsqu'aucune n'est indiquée

Intégration de serveur à serveur

Pour les intégrations backend (sans widget), le flux est identique : appelez d'abord bootstrap pour obtenir un token, puis envoyez le retour à ingest. La différence est que vous devez vous assurer que le domaine d'origine figure dans la liste des domaines autorisés de la source de retours, ou configurer la source sans restrictions de domaine.

Lier les retours aux idées

Les retours ingérés peuvent être liés aux éléments d'Idea Hub à l'aide de l'outil MCP link_feedback_to_idea_item. Cela assure la traçabilité entre les retours des utilisateurs et les décisions produit.