API

L'API — vue d'ensemble

Les clés, les droits, l'expiration, les limites et les erreurs, communs à nos API. Chaque logiciel documente ses routes sur sa propre installation.

Lead Empire, Media Empire et Mail Empire ont chacun une API REST (en JSON) et un serveur MCP pour les assistants d'IA.

Où est la documentation de chaque API#

Chaque installation sert sa propre documentation, toujours à jour avec sa version, lisible sans connexion :

Logiciel	Adresse de l'API	Documentation complète
Lead Empire	`https://<votre-installation>/api/v1`	`https://<votre-installation>/docs/api`
Media Empire	`https://media.successarchitect.fr/api`	media.successarchitect.fr/docs/api
Mail Empire	`https://<votre-installation>/api/rest/v1`	`https://<votre-installation>/docs/api`

<votre-installation> est l'adresse de votre Lead Empire, ou de votre Mail Empire : chaque client a les siennes, une par logiciel. Vous la trouvez dans la barre d'adresse après avoir cliqué sur « Ouvrir Lead Empire » ou « Ouvrir Mail Empire » dans votre espace. La page /docs/api de votre installation l'affiche en haut, avec l'adresse de son serveur MCP.

Les clés#

Une clé se crée dans le logiciel, par un compte connecté (jamais avec une autre clé) :

	Lead Empire	Media Empire	Mail Empire
Où	Réglages → Compte et équipe → Clés API	Réglages → API	Paramètres → API
Forme	`le_…`	`yft_…`	`me_…`
Droits	Choisis à la création : préréglages ou sur mesure	Choisis à la création : lecture, création, publication, dépense	Choisis à la création : lecture, création, dépense, envoi, suppression
Expiration	Au choix (7, 30, 90 ou 365 jours), ou aucune	7, 30, 90 ou 365 jours, ou jamais	7, 30, 90 ou 365 jours (obligatoire)
Débit	60 appels par minute par défaut (de 10 à 5 000)	60 appels par minute par défaut (de 10 à 600)	60 appels par minute par défaut (de 10 à 600)
Journal	Chaque appel, par clé, dans Réglages → Clés API	Chaque appel, gardé 90 jours (bouton « Journal »)	Chaque appel, gardé un an (« Ce que votre IA a fait »), et l'usage de chaque clé

Pour toutes nos clés :

le secret ne s'affiche qu'une fois, à la création : le serveur n'en garde qu'une empreinte et ne peut pas vous le remontrer ;
il voyage dans l'en-tête Authorization: Bearer <clé>, jamais dans l'adresse ;
une clé agit au nom du compte qui l'a créée, avec les droits de ce compte au moment de l'appel : une page fermée au compte l'est aussi à la clé ;
révoquer une clé la refuse dès l'appel suivant ; une clé expirée est refusée ;
« Tout arrêter » coupe d'un coup toutes les clés et tous les accès d'IA du compte, jusqu'à ce que vous les rétablissiez.

Les droits#

Une clé n'a que les droits cochés à sa création. Les droits qui coûtent ou qui font sortir quelque chose de vos logiciels sont toujours des cases à part, décochées par défaut.

Ce que fait le droit	Lead Empire	Media Empire	Mail Empire
Lire	`me:read`, `companies:read`, `lists:read`	`read` (toujours compris)	`read` (toujours compris)
Créer, modifier	`lists:write`, `lists:operate` (enchaînements)	`create`	`write` (brouillons, leads, pause)
Dépenser (quotas, crédits)	`companies:enrich`, `companies:crawl`, `lists:operate` (selon les étapes)	`spend`	`spend` (aperçu d'un e-mail écrit par l'IA)
Faire sortir (envoi, publication)	`lists:export` (envoi vers Mail Empire)	`publish`	`send` (lancer une campagne — attend un clic, sauf autorisation)
Supprimer	`lists:delete`	`create` (et `publish` pour un projet partagé par lien)	`delete` (attend un clic, sauf autorisation)

Le détail, route par route, est sur la page de chaque logiciel.

Les limites#

Le débit de chaque clé (voir le tableau). Au-delà : HTTP 429 et l'en-tête Retry-After (en secondes).
Les quotas mensuels de votre formule (Lead Empire : enrichissements, crawls…), les crédits (Media Empire : vidéos, avatars, musiques…) et le plafond d'IA du mois (Mail Empire). Lead Empire répond 402 quota_exceeded quand un quota est atteint.
Les plafonds de l'IA, quand c'est un assistant d'IA qui agit par le MCP : voir les garde-fous.

Les erreurs#

Une erreur répond par un statut HTTP et un code stable en JSON :

JSON

{ "error": "insufficient_scope", "required": "publish" }

Statut	Ce qu'il veut dire	Que faire
`400`	Requête mal formée	Corriger la requête
`401`	Pas de clé, clé inconnue, révoquée ou expirée	Vérifier la clé, ou en créer une
`402`	Quota mensuel atteint (Lead Empire)	Attendre le mois suivant, ou changer de formule
`403`	Droit manquant, page fermée au compte, accès arrêté (« Tout arrêter »), compte inactif	Lire le code d'erreur : il dit lequel
`404`	Ressource introuvable, ou pas à vous	Vérifier l'identifiant
`409`	Conflit : une opération tourne déjà, ou un logiciel lié n'est pas relié	Attendre, ou lire le message
`422`	Paramètres refusés (`message` et `errors` disent lesquels)	Corriger les paramètres
`429`	Trop d'appels	Attendre `Retry-After` secondes
`503`	Un service public interrogé ne répond pas	Réessayer plus tard

La liste exacte des codes de chaque logiciel est dans sa documentation.

Les versions#

/api/v1 ne change que par ajouts : nouvelles routes, nouveaux champs. Lisez les réponses en ignorant les champs que vous ne connaissez pas.
Un retrait est annoncé au moins six mois avant, avec les en-têtes Deprecation et Sunset ; un changement incompatible ouvrirait /api/v2.
Un outil MCP retiré reste trois mois, avec une description qui dit par quoi il est remplacé.
Les changements sont listés dans les Nouveautés.

Par où continuer#

API de Lead EmpireRecherche, listes, enrichissement, enchaînements, envoi vers Mail Empire.
API de Media EmpireProjets, rendus, publications, vidéos, export du compte.
API de Mail EmpireCampagnes, leads, réponses, brouillons ; lancer et supprimer avec un clic humain.
Le MCPLa même chose, pour votre assistant d'IA.