API REST

Raconte expose une API REST pour gérer les interviews et les invitations directement en HTTP. C’est la même surface que pilote le serveur MCP, accessible depuis n’importe quel client HTTP. Utilisez MCP pour qu’un agent IA opère le produit, et l’API REST pour intégrer depuis votre propre backend. Pour le terminal et les scripts, utilisez le CLI ; pour une application TypeScript ou Node, le SDK.

La référence complète et interactive (chaque endpoint, paramètre, schéma, avec un “essayer” intégré) se trouve ici :

URL de base

https://api.raconte.ai

Chaque chemin est préfixé par la version de l’API, par exemple https://api.raconte.ai/v1/interviews. Un changement cassant passe par un nouveau segment de version plutôt que par une modification de v1, et une version retirée répond d’abord avec les en-têtes Deprecation et Sunset pendant au moins six mois. La page développeurs donne la politique complète.

Authentification

L’authentification utilise une clé d’API d’organisation, créée depuis Paramètres → API dans l’application et limitée à une organisation. Chaque requête s’exécute dans le périmètre de cette organisation ; les ressources des autres organisations ne sont jamais renvoyées.

La valeur complète n’est affichée qu’une fois, à la création. Conservez-la en lieu sûr : ensuite, seul le préfixe reste visible.

Passez la clé en tant que jeton Bearer :

Authorization: Bearer VOTRE_CLE_API

Un en-tête x-api-key: VOTRE_CLE_API est également accepté.

curl https://api.raconte.ai/v1/interviews \
  -H "Authorization: Bearer VOTRE_CLE_API"

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, partagé entre tous les endpoints. Au-delà, l’API répond 429 avec un en-tête Retry-After qui donne le nombre de secondes à attendre.

Erreurs

Les erreurs reviennent en JSON, jamais en page HTML. La plupart portent le statut HTTP, un libellé error court et un message lisible. Une validation en échec répond 400 avec le détail champ par champ dans un tableau errors. Les deux formes sont typées dans la spécification. La page développeurs montre un exemple de chacune.

Ce que vous pouvez faire

• Interviews : créer, lister, lire, modifier, archiver/restaurer, régénérer l’intro ou le premier message, et lire les journaux d’activité.
• Invitations : créer (unitaire ou en masse), lister, lire, modifier, envoyer, annuler, réactiver, archiver/restaurer, lire les journaux, et obtenir une URL audio signée pour un message.

Les opérations au niveau du compte (facturation, webhooks, gestion des clés d’API, réglages de l’organisation) ne sont pas accessibles via les clés d’API : elles restent dans l’application authentifiée.

Consultez la référence interactive pour tous les schémas de requête et de réponse.