Introduction à l'API

L’API REST Famulor permet de gérer les mêmes ressources client que celles disponibles dans le tableau de bord : assistants, appels, campagnes, transcriptions, connaissances et paramètres d’espace de travail.

Pour un processus métier en plusieurs étapes — enrichir un prospect, puis appeler, puis mettre à jour un CRM, puis notifier un canal —, une automatisation demande souvent moins de code à maintenir que de connecter vous-même chaque étape. Utilisez l’API directement lorsque vous avez besoin d’un contrôle programmatique simple et immédiat, comme déclencher un appel unique depuis votre propre application.

URL de base

https://app.famulor.io/api/v1

Si vous utilisez un domaine en marque blanche, remplacez app.famulor.io par ce domaine. Les chemins restent identiques.

Accès à l’API

Les requêtes REST nécessitent API Access dans le forfait de l’espace de travail ou sous forme d’option récurrente. Si cet accès est retiré, les clés API et identifiants OAuth existants restent consultables et révocables par les administrateurs de l’espace de travail, mais les requêtes /api/v1 ordinaires renvoient 403 api_access_required. Après l’échec d’un paiement de forfait, POST /api/v1/billing/invoice-payment et POST /api/v1/billing/portal restent disponibles avec un identifiant valide afin qu’un propriétaire puisse régulariser la facturation. Les contrôles d’authentification, de rôle et de portée continuent de s’appliquer.

Authentification

Envoyez un jeton Bearer dans l’en-tête Authorization :

curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Deux types d’identifiants sont pris en charge :

Workspace API keys (fam_...) — créez-les sous Settings → API & MCP pour les intégrations serveur à serveur. La clé complète n’est affichée qu’une seule fois. Le tableau de bord n’offre pas de sélecteur de portées, donc une clé qui y est créée porte toujours toutes les portées. Pour générer une clé plus restreinte, appelez POST /api/v1/api-keys ou POST /api/v1/workspaces/{workspace_id}/api-keys avec un tableau scopes explicite — les portées de la nouvelle clé doivent être un sous-ensemble de celles de l’identifiant qui la crée.
OAuth 2.0 access tokens (fam_at_...) — utilisez Authorization Code avec PKCE-S256 pour les applications agissant au nom d’un utilisateur connecté.

L’accès autorisé par un utilisateur suit son appartenance et son rôle actuels dans l’espace de travail. Les clés API d’espace de travail continuent de suivre leur propre statut et leurs propres portées jusqu’à ce qu’un administrateur autorisé de l’espace de travail les révoque.

Traitez les clés API comme des mots de passe. Ne les intégrez jamais dans du code de navigateur ou d’application mobile ; utilisez OAuth pour les applications destinées aux utilisateurs.

Hygiène des clés

Stockez les clés dans des variables d’environnement ou un gestionnaire de secrets, jamais dans le contrôle de version.
Limitez chaque clé au strict nécessaire pour l’intégration — une clé qui ne fait que lire les appels ne devrait pas aussi avoir assistants:write. Les clés créées depuis le tableau de bord ont toujours un accès complet ; utilisez le chemin API ci-dessus pour en générer une aux portées restreintes.
Faites tourner les clés périodiquement, et immédiatement après le départ de toute personne y ayant accès.
Révoquer une clé depuis Settings → API & MCP prend effet immédiatement ; les requêtes déjà en cours peuvent tout de même aboutir.

Exigences des clients OAuth

Un client développé sur mesure pilote directement les points de terminaison d’autorisation et de jeton :

https://app.famulor.io/api/oauth/authorize
https://app.famulor.io/api/oauth/token

Utilisez des URL de redirection HTTPS. Les applications natives peuvent aussi utiliser des adresses HTTP de bouclage littérales telles que 127.0.0.1. Les demandes d’autorisation OAuth doivent utiliser PKCE-S256 et ne demander que les portées enregistrées pour le client. En cas de limitation de débit, réessayez après le délai indiqué par la réponse. Le client utilise soit des identifiants préapprouvés pour votre espace de travail, soit s’enregistre lui-même dynamiquement avec POST /api/oauth/register — en fournissant entre 1 et 10 redirect_uris uniques. Les points de terminaison, les portées prises en charge et les types d’octroi sont détectables via /.well-known/oauth-authorization-server. Un client enregistré dynamiquement que l’utilisateur n’a pas encore approuvé ne reçoit pas d’erreurs sur son URL de redirection : une demande d’autorisation invalide reçoit sa réponse directement sur la page d’autorisation. Une fois le client approuvé, les connexions suivantes n’obtiennent que les groupes d’outils choisis par l’utilisateur ; s’il en demande davantage, l’écran de consentement s’affiche à nouveau. Les jetons d’accès se renouvellent avec l’octroi refresh_token. Les jetons de rafraîchissement changent à chaque utilisation : demander un nouveau jeton d’accès émet aussi un nouveau jeton de rafraîchissement et invalide immédiatement celui que vous avez envoyé.

Format des réponses

Les réponses réussies placent le résultat dans data et peuvent inclure meta :

{
  "data": [{ "id": "…", "name": "Support Agent" }],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}

Les réponses ne contiennent que des données d’espace de travail destinées au client. Les secrets ne sont jamais renvoyés après leur enregistrement, et les valeurs sensibles sont masquées lorsque c’est utile. Les enregistrements sont fournis via des liens temporaires. L’usage et la facturation sont exprimés dans les minutes et crédits affichés sur votre compte.

Pagination

Les points de terminaison de liste utilisent limit et offset :

Paramètre	Valeur par défaut	Maximum	Description
`limit`	`50`	`200`	Nombre d’éléments à renvoyer
`offset`	`0`	—	Nombre d’éléments à ignorer

Utilisez meta.pagination.total pour déterminer si d’autres pages sont disponibles.

Erreurs

Les échecs renvoient un code stable et un message lisible :

{
  "error": {
    "code": "invalid_request",
    "message": "A destination phone number is required."
  }
}

Statut	Code	Signification
`400`	`invalid_request`	Corps ou paramètres de requête invalides
`401`	`unauthorized`	Identifiant manquant, invalide, expiré ou révoqué
`403`	`forbidden`	La portée, le rôle ou le forfait n’autorise pas l’action
`403`	`api_access_required`	API Access n’est pas disponible pour cet espace de travail
`404`	`not_found`	Ressource introuvable ou non visible pour cet espace de travail
`409`	`conflict`	La ressource est dans un état conflictuel
`429`	`rate_limited`	Trop de requêtes ; patientez puis réessayez
`500`	`internal_error`	Erreur inattendue

Gestion des clients en marque blanche

Les revendeurs autorisés peuvent utiliser les points de terminaison platform pour gérer leurs propres clients finaux, émettre et révoquer des jetons API client, transférer des crédits, et gérer leur domaine personnalisé. Ces points de terminaison nécessitent les portées platform:read ou platform:write ; les opérations sur le domaine personnalisé utilisent la portée de paramètres correspondante.

Point de terminaison	Objectif
`GET /api/v1/platform/users`	Lister vos clients finaux
`POST /api/v1/platform/users`	Inscrire un client final
`GET /api/v1/platform/users/{user_id}`	Lire le résumé de compte d’un client final
`POST /api/v1/platform/users/{user_id}/token`	Émettre un jeton API pour ce client
`POST /api/v1/platform/users/login`	Authentifier un client
`POST /api/v1/platform/users/{user_id}/logout`	Révoquer les jetons API de ce client
`POST /api/v1/platform/users/{user_id}/balance`	Transférer des crédits entre votre solde revendeur et le client
`GET /api/v1/custom-domain`	Lire l’état du domaine personnalisé
`POST /api/v1/custom-domain`	Ajouter un domaine personnalisé et recevoir les enregistrements DNS requis
`POST /api/v1/custom-domain/verify`	Vérifier le DNS et activer un domaine prêt
`DELETE /api/v1/custom-domain`	Supprimer le domaine personnalisé

Consultez le guide de l’API marque blanche pour des exemples.

CLI

Chaque opération de l’API est aussi une commande de la CLI Famulor, avec votre clé API stockée dans le trousseau du système :

npm install --global famulor
famulor auth login
famulor list-assistants --output table

La CLI utilise les mêmes clés API, portées, API Access et limites de requêtes que l’API REST.

MCP

Les mêmes fonctionnalités destinées aux clients sont disponibles sous forme d’outils IA via le point de terminaison MCP :

https://app.famulor.io/mcp

MCP utilise les mêmes clés API, le même consentement OAuth, les mêmes portées et le même accès aux espaces de travail. Sa disponibilité est contrôlée séparément par Connect AI / MCP, et non par API Access.

Variantes Realtime et voix de conversation

Créez ou modifiez un assistant avec mode: "realtime" et realtime_variant: "full_duplex" lorsque votre espace de travail y a accès. Sans variante, les nouveaux assistants restent en Standard et les mises à jour conservent la variante existante. Le modèle de raisonnement est géré centralement ; les préférences Pipeline de l’assistant ne le remplacent pas. Utilisez GET /api/v1/voices?mode=realtime&realtime_variant=full_duplex pour découvrir les voix compatibles. Transmettez l’id retourné dans realtime_voice ; Full Duplex l’utilise aussi pour les salutations, le consentement et les annonces des outils. Conservez tts_voice comme voix de secours Pipeline. Les salutations audio importées conservent leur voix enregistrée. Les identifiants de voix sont opaques ; n’en déduisez aucun fournisseur. Toute voix ou variante indisponible est refusée. Pour les voix TTS, utilisez GET /api/v1/voices?mode=tts&language=de sans realtime_variant. Associer mode=tts à une variante Realtime renvoie 400. CLI : famulor list-voices --mode tts --language de ; pour Full Duplex : famulor list-voices --mode realtime --realtime-variant full_duplex --language de. Lorsqu’un extrait natif enregistré est disponible, preview_url contient un chemin API relatif. Résolvez-le par rapport à votre domaine API et téléchargez-le avec le même jeton Bearer et la portée voices:read. GET /api/v1/voices/{id}/preview?realtime_variant=full_duplex renvoie un fichier WAV sans générer de nouvel extrait. Le catalogue vocal MCP fournit la même référence de prévisualisation. Les échantillons TTS enregistrés sont disponibles via GET /api/v1/voices/{id}/preview?mode=tts, ou famulor get-voice-preview --id <voice-id> --mode tts dans la CLI. Utilisez la valeur preview_url retournée ; elle vaut null si aucun échantillon n’est disponible. Le téléchargement ne génère pas de nouvel audio. Si votre forfait autorise la sélection de modèles, GET /api/v1/models?type=realtime&realtime_variant=full_duplex liste les modèles vocaux compatibles. Cela ne donne pas accès à un sélecteur de modèle de raisonnement. La réponse Usage inclut les tarifs actuels en crédits. Les suppléments Full Duplex et avatar s’additionnent lorsque les deux sont actifs. Disponibilité régionale : Full Duplex dépend des modèles activés pour la région choisie de votre espace, y compris EU, US et Global. Il nécessite l’accès bêta, un forfait incluant Realtime et des modèles de parole et de raisonnement compatibles. L’éditeur, l’API et MCP appliquent les mêmes règles de disponibilité. MCP utilise les mêmes champs d’assistant. L’outil get_voices accepte mode et realtime_variant ; get_models accepte realtime_variant. Consultez les modes de moteur pour les réglages et limites.

Limites de requêtes

Les requêtes REST partagent un budget fixe d’une minute sur tous les endpoints : par défaut, 120 requêtes par clé API ou jeton d’accès OAuth et 600 requêtes par espace de travail. Votre forfait peut prévoir d’autres limites. Ajouter des clés ou changer de domaine n’augmente pas le budget de l’espace de travail. Une limite distincte de 1 800 requêtes par minute et par adresse IP protège la vérification des identifiants ; les intégrations partageant une IP partagent cette limite. Lorsque le budget est épuisé, l’API renvoie 429, error.code: "rate_limited" et un en-tête Retry-After indiquant le délai en secondes. Suspendez les requêtes pendant ce délai, puis réessayez avec des délais croissants et une petite variation aléatoire. Évitez les interrogations continues et utilisez les webhooks lorsque disponibles. Si la protection des requêtes est temporairement indisponible, l’API renvoie 503 avec un délai de nouvelle tentative. Le tableau de bord et MCP appliquent leurs propres règles d’accès et de requêtes.

​URL de base

​Accès à l’API

​Authentification

​Hygiène des clés

​Exigences des clients OAuth

​Format des réponses

​Pagination

​Erreurs

​Gestion des clients en marque blanche

​CLI

​MCP

​Variantes Realtime et voix de conversation

​Limites de requêtes

URL de base

Accès à l’API

Authentification

Hygiène des clés

Exigences des clients OAuth

Format des réponses

Pagination

Erreurs

Gestion des clients en marque blanche

CLI

MCP

Variantes Realtime et voix de conversation

Limites de requêtes