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âchePossibleComment
Créer une interview à partir d’un promptOuiPOST /v1/interviews, l’outil MCP create-interview ou raconte interviews create
Envoyer le lien à de vraies personnesOuiPassez 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éponseOuiÀ la demande par REST et MCP, ou poussés par le webhook interview.completed
Récupérer l’audioOui, par RESTUne URL présignée pour l’enregistrement de chaque message
Savoir quand une interview démarre ou se termineOuiLes webhooks interview.started et interview.completed
Recruter des participantsNonVous amenez les personnes : vos utilisateurs, vos clients, un panel avec lequel vous travaillez déjà
Simuler des participantsNonChaque réponse vient d’une vraie personne qui parle
Produire un rapport sur plusieurs interviewsNonVotre 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 :

Terminal window
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

RessourceURL
Index de l’API (URL de base)api.raconte.ai
Spécification OpenAPI 3.1raconte.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 LLMraconte.ai/llms.txt
Skill agent pour le CLIraconte.ai/skill.md
Guide d’authentificationraconte.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 machineraconte.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

Démarrage rapide

Terminal window
npm install -g @raconte/cli
export RACONTE_API_KEY="VOTRE_CLE_API"
raconte interviews create \
--prompt "Interroge sur l'onboarding : ce qui a bloqué, ce qui manquait" \
--email jane@example.com

La 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 :

  1. Un module HTTP appelle POST /v1/interviews avec le prompt et les invitees, en passant la clé d’API en jeton bearer. Raconte envoie à chaque personne son lien par email.
  2. Un déclencheur webhook reçoit interview.completed et 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=60
RateLimit-Limit: 300
RateLimit-Remaining: 297
RateLimit-Reset: 42

Le 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.