Raconte pour les développeurs
Avec Raconte, un agent IA mène des interviews vocales auprès de vraies personnes et en récupère les transcripts. L’agent crée une interview à partir d’un prompt. Raconte envoie le lien par email à chaque personne, ou renvoie un lien unique à partager. Un intervieweur IA mène la conversation et pose des questions de relance. Une fois l’appel terminé, l’agent lit le transcript complet, un résumé et le sentiment de chaque réponse. Les interviews et les invitations sont exposées par une API REST, un serveur MCP, un SDK typé et un CLI, qui acceptent tous la même clé d’API d’organisation.
Les capacités et les limites de l’API
| Tâche | Possible | Comment |
|---|---|---|
| Créer une interview à partir d’un prompt | Oui | POST /v1/interviews, l’outil MCP create-interview ou raconte interviews create |
| Envoyer le lien à de vraies personnes | Oui | Passez invitees et Raconte écrit à chacune par email, ou omettez-les et partagez vous-même l’URL renvoyée |
| Récupérer le transcript, le résumé et le sentiment de chaque réponse | Oui | À la demande par REST et MCP, ou poussés par le webhook interview.completed |
| Récupérer l’audio | Oui, par REST | Une URL présignée pour l’enregistrement de chaque message |
| Savoir quand une interview démarre ou se termine | Oui | Les webhooks interview.started et interview.completed |
| Recruter des participants | Non | Vous amenez les personnes : vos utilisateurs, vos clients, un panel avec lequel vous travaillez déjà |
| Simuler des participants | Non | Chaque réponse vient d’une vraie personne qui parle |
| Produire un rapport sur plusieurs interviews | Non | Votre agent lit les transcripts par l’API ou MCP et fait la comparaison |
Obtenir une clé
Créez une clé d’API d’organisation depuis Paramètres → API dans l’application. La valeur complète s’affiche une seule fois, à la création. Chaque clé est rattachée à une organisation : les requêtes ne voient jamais que les interviews, invitations et transcripts de celle-ci.
Une clé porte toute la surface publique, listée sous les noms interviews:read, interviews:write, invitations:read et invitations:write dans les métadonnées de la ressource protégée. Ces noms décrivent ce qu’un appel peut faire. On ne peut pas les demander un par un, donc il n’existe pas de clé plus restreinte.
Passez-la en jeton bearer :
curl https://api.raconte.ai/v1/interviews \ -H "Authorization: Bearer VOTRE_CLE_API"Un en-tête x-api-key: VOTRE_CLE_API est également accepté.
Un appel sans clé répond 401 avec un en-tête WWW-Authenticate qui nomme les métadonnées de la ressource protégée (RFC 9728) : une seule requête ratée suffit à un agent pour découvrir comment s’authentifier. Le même parcours est décrit en prose dans auth.md : d’où vient une clé, comment l’envoyer, ce que signifie chaque erreur, comment la révoquer. Raconte émet des clés d’API plutôt que d’exploiter un serveur d’autorisation OAuth, donc pas d’enregistrement dynamique de client : une personne crée la clé et vous la transmet.
Points d’entrée lisibles par une machine
| Ressource | URL |
|---|---|
| Index de l’API (URL de base) | api.raconte.ai |
| Spécification OpenAPI 3.1 | raconte.ai/openapi.json |
| Référence interactive | /fr/docs/api-reference |
| Carte du serveur MCP | /.well-known/mcp/server-card.json |
| Index du site pour les LLM | raconte.ai/llms.txt |
| Skill agent pour le CLI | raconte.ai/skill.md |
| Guide d’authentification | raconte.ai/auth.md |
| Métadonnées de la ressource protégée (RFC 9728) | api.raconte.ai/.well-known/oauth-protected-resource |
| Catalogue d’API (RFC 9727) | /.well-known/api-catalog |
| Catalogue Agentic Resource Discovery | /.well-known/ai-catalog.json |
| Index Agent Skills | /.well-known/agent-skills/index.json |
| Tarifs, lisibles par une machine | raconte.ai/pricing.md |
Chaque page de la documentation de Raconte a aussi son jumeau markdown : ajoutez .md à son URL, ou envoyez l’en-tête Accept: text/markdown.
Quand l’index du site entier représente plus de contexte que nécessaire, quatre index ciblés couvrent une seule zone : /developers/llms.txt, /docs/llms.txt, /guides/llms.txt et /blog/llms.txt.
Les quatre surfaces
- API REST : 26 opérations HTTP sur les interviews et les invitations, transcripts, journaux d’activité et URL audio présignées compris. URL de base
https://api.raconte.ai, chaque chemin préfixé par/v1. - Serveur MCP : huit outils en Streamable HTTP sur
https://api.raconte.ai/api/mcp, pour que Claude, Cursor, Opencode et les autres clients MCP pilotent le produit nativement. Le handshake ettools/listsont ouverts, donc un client peut lire le catalogue avant d’avoir une clé. Chaque client demande sa propre configuration MCP. - Webhooks : un POST signé vers votre endpoint quand une interview démarre ou se termine, pour pousser les transcripts dans vos propres systèmes.
- SDK et CLI :
@raconte/node-sdkpour les applications TypeScript et Node,@raconte/clipour les terminaux, les scripts et les agents IA. Le SDK est généré depuis la spécification OpenAPI, il ne peut donc pas diverger de l’API.
Démarrage rapide
npm install -g @raconte/cliexport RACONTE_API_KEY="VOTRE_CLE_API"
raconte interviews create \ --prompt "Interroge sur l'onboarding : ce qui a bloqué, ce qui manquait" \ --email jane@example.comLa commande renvoie l’interview créée et ses invitations en JSON, lien de partage compris. Depuis TypeScript, le même appel passe par le SDK :
import { createRaconteClient, interviewsControllerCreate } from '@raconte/node-sdk'
const client = createRaconteClient({ apiKey: process.env.RACONTE_API_KEY! })
const { data, error } = await interviewsControllerCreate({ client, body: { prompt: 'Interroge sur l\'onboarding : ce qui a bloqué, ce qui manquait' },})Depuis n8n ou Make
n8n et Make se connectent à Raconte avec leurs modules standards de requête HTTP et de webhook. Un workflow type en utilise un de chaque :
- Un module HTTP appelle
POST /v1/interviewsavec le prompt et lesinvitees, en passant la clé d’API en jeton bearer. Raconte envoie à chaque personne son lien par email. - Un déclencheur webhook reçoit
interview.completedet transmet le transcript et le résumé aux étapes suivantes, qui peuvent ajouter une note dans le CRM, envoyer un message Slack ou ajouter une ligne à un tableur.
Raconte livre chaque webhook en une seule tentative, sans nouvel essai si votre endpoint échoue : si votre workflow ne doit manquer aucune interview, faites-lui aussi lister les invitations de l’interview à intervalle régulier et vérifier leur statut.
Quand un workflow n8n fait tourner un agent IA, le nœud MCP Client Tool branche cet agent sur le serveur MCP, donc l’agent crée les interviews et lit les transcripts lui-même. Configurez le nœud comme n’importe quel client MCP, avec l’URL du serveur et l’en-tête de la clé d’API. L’agent accepte ensuite des demandes en langage courant pour chaque étape d’une interview, de sa création à la lecture du transcript.
Tester sans consommer de minutes
Il n’y a pas d’hôte bac à sable séparé : l’API tourne sur votre vraie organisation, et le plan gratuit suffit à explorer. Créer des interviews, des invitations et des liens ne coûte rien, car la facturation ne compte que les minutes d’interview actives. Chaque organisation dispose en plus de 60 minutes offertes par mois. Créez une interview jetable, passez un appel dessus vous-même, puis archivez-la.
Pour un essai à blanc sans aucun appel, créez une interview sans invitees. Vous récupérez une invitation READY et son URL de partage. Rien n’est facturé tant que personne ne parle.
Quotas
Chaque réponse porte les en-têtes RateLimit de l’IETF, pour qu’un client se régule sans deviner :
RateLimit-Policy: 300;w=60RateLimit-Limit: 300RateLimit-Remaining: 297RateLimit-Reset: 42Le quota est de 300 requêtes par minute et par clé d’API. Au-delà, l’API répond 429 avec un en-tête Retry-After qui donne le nombre de secondes à attendre. Réessayez après ce délai plutôt qu’immédiatement.
Versioning et dépréciation
Chaque chemin est préfixé par la version de l’API : https://api.raconte.ai/v1/interviews. La spécification, le SDK et le CLI l’utilisent tous, donc une intégration bâtie sur l’un d’eux est versionnée sans effort de votre côté.
Un changement cassant passe par un nouveau segment de version plutôt que par une modification de v1. Quand une version est retirée, les réponses concernées portent les en-têtes Deprecation et Sunset (RFC 9745 et RFC 8594) pendant au moins six mois avant l’arrêt de l’endpoint. La date de retrait est annoncée sur cette page. Les deux en-têtes sont déclarés sur chaque réponse dans la spécification, pour qu’un client puisse les détecter automatiquement.
Erreurs
Les erreurs reviennent en JSON, jamais en page HTML. La plupart portent le statut HTTP, un libellé error court et un message lisible :
{ "statusCode": 404, "error": "Not Found", "message": "Interview not found"}Un corps ou un paramètre qui échoue à la validation répond 400 avec le détail champ par champ, une entrée par valeur rejetée :
{ "statusCode": 400, "timestamp": "2026-08-22T14:30:47.304Z", "path": "/v1/interviews", "errors": [ { "path": ["prompt"], "code": "too_small", "message": "Too small: expected string to have >=10 characters" } ]}Les deux formes sont typées dans la spécification, donc le SDK et n’importe quel client généré savent à quoi s’attendre. La référence interactive liste les statuts que chaque opération peut renvoyer.
Obtenir de l’aide
Écrivez à contact@raconte.ai avec l’identifiant de l’interview ou de l’invitation concernée. Pour le volume, la marque blanche, le SSO ou un SLA, demandez une proposition pour l’offre Entreprise en indiquant le nombre d’interviews prévu par mois et leurs langues.