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

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.

​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

​MCP

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

MCP