Raconte pour les développeurs

Raconte se pilote depuis du code. Les interviews et les invitations sont exposées par une API REST, un serveur MCP, un SDK typé et un CLI, tous sur la même surface et la même clé d’API d’organisation.

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.

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. La version en prose du même sujet est 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

Chaque page de documentation 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 et tools/list sont ouverts, donc un client peut lire le catalogue avant d’avoir une clé. Le guide d’installation donne la configuration par client.
• 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-sdk pour les applications TypeScript et Node, @raconte/cli pour les terminaux, les scripts et les agents IA. Le SDK est généré depuis la spécification ci-dessus, il ne peut donc pas diverger de l’API.

Démarrage rapide

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' },
})

Tester sans consommer de minutes

Il n’y a pas de host 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, la facturation ne compte que les minutes d’interview actives, et chaque organisation dispose 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, et 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, et la date 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 guetter sans lire ce paragraphe.

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, la page contact indique les éléments utiles à envoyer.