Pour les développeurs
Une API en lecture seule + un serveur MCP pour vos données de visibilité IA
Récupérez votre score de visibilité et le détail des mentions par moteur dans vos propres tableaux de bord, scripts, ou un agent IA (Claude Desktop, Cursor, un agent LangChain sur mesure) — limité aux seules marques que votre compte suit. Disponible sur chaque plan payant, sans coût additionnel.
Démarrage rapide
Trois étapes
- 1Créez une clé sur votre page de compte — affichée une seule fois, copiez-la immédiatement.
- 2Envoyez-la en Authorization: Bearer <clé> sur chaque requête — REST ou MCP.
- 3Appelez un endpoint ci-dessous, ou pointez un client MCP vers `/api/mcp`.
API REST
GET /api/v1/visibility
Le score actuel d'une marque + le détail par moteur. `domain` doit être une marque suivie par votre compte avec au moins un scan terminé.
Requête
curl "https://pingmybrand.com/api/v1/visibility?domain=acme.com" \ -H "Authorization: Bearer pmb_live_xxxxxxxxxxxxxxxx"
Réponse 200
{
"domain": "acme.com",
"visibilityScore": 62,
"updatedAt": "2026-07-14T09:02:11.000Z",
"engines": [
{
"engine": "openai",
"status": "measured",
"score": 71,
"mentionRate": 0.68,
"avgPosition": 1.4,
"citationRate": 0.32
},
{
"engine": "anthropic",
"status": "measured",
"score": 58,
"mentionRate": 0.52,
"avgPosition": 2.1,
"citationRate": 0.2
}
// … une entrée par moteur (openai, anthropic, google, perplexity, grok)
]
}API REST
GET /api/v1/brands
Chaque marque suivie par votre compte, avec le score le plus récent de chacune (null — jamais un chiffre fabriqué — pour une marque sans scan terminé).
Requête
curl "https://pingmybrand.com/api/v1/brands" \ -H "Authorization: Bearer pmb_live_xxxxxxxxxxxxxxxx"
Réponse 200
{
"brands": [
{ "domain": "acme.com", "visibilityScore": 62, "updatedAt": "2026-07-14T09:02:11.000Z" },
{ "domain": "acme-labs.io", "visibilityScore": null, "updatedAt": null }
]
}API REST
Erreurs et limites de débit
Chaque échec est un vrai statut HTTP avec un corps { error } — jamais un 200 fabriqué avec des données factices.
| Statut | Quand |
|---|---|
| 401 | la clé porteur est absente, mal formée, ou ne correspond à aucun compte |
| 403 | le compte de la clé n'a pas de plan payant actif (l'API est une fonctionnalité des plans payants) |
| 404 | le domaine n'est pas suivi par ce compte, ou est suivi mais n'a jamais terminé de scan |
| 429 | vous avez dépassé 120 requêtes/heure sur cette clé pour cet endpoint (en-tête Retry-After inclus) |
120 requêtes/heure par clé, suivies séparément pour chaque endpoint — épuiser `/api/v1/visibility` n'affecte pas `/api/v1/brands` ni le serveur MCP.
Webhooks
POST /api/v1/webhooks
Enregistrez une URL de rappel et recevez un POST signé HMAC chaque fois qu'une marque suivie par votre compte a un VRAI changement de score suite à un scan — sans polling. Enregistrer à nouveau remplace toute inscription précédente et émet un nouveau secret ; un seul webhook actif par compte, comme votre clé API.
Enregistrement
curl -X POST "https://pingmybrand.com/api/v1/webhooks" \
-H "Authorization: Bearer pmb_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "url": "https://your-server.example/pingmybrand-hook" }'Réponse 200
{
"url": "https://your-server.example/pingmybrand-hook",
"secret": "8h3k...redacted...9fZ",
"createdAt": "2026-07-17T09:02:11.000Z"
}
// "secret" n'est montré qu'une seule fois — sauvegardez-le pour vérifier les livraisons.GET /api/v1/webhooks renvoie votre inscription actuelle (jamais le secret à nouveau) plus recentFailureCount / lastFailureAt — vos échecs de livraison récents épuisés, pour savoir si votre endpoint est cassé sans fouiller dans les logs ; DELETE /api/v1/webhooks le révoque.
Payload livré
POST https://your-server.example/pingmybrand-hook
X-PingMyBrand-Signature: sha256=9f2a...
{
"event": "scan_completed",
"domain": "acme.com",
"slug": "acme-com-x1",
"score": 62,
"previousScore": 40,
"delta": 22,
"engines": [
{ "engine": "openai", "status": "live", "score": 71 }
// … une entrée par moteur
],
"timestamp": "2026-07-17T09:02:11.000Z"
}Vérifiez que chaque livraison vient vraiment de PingMyBrand avant de lui faire confiance — recalculez le HMAC-SHA256 sur le corps brut de la requête avec votre secret et comparez à l'en-tête X-PingMyBrand-Signature.
Vérification (Node.js)
import crypto from "crypto";
function verify(secret, rawBody, header) {
const [, sig] = header.split("=");
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
}Réessayé jusqu'à 4 fois avec repli exponentiel (0,5 s, 1 s, 2 s) en cas de livraison échouée (réponse non-2xx ou erreur réseau) avant abandon. Ne se déclenche que sur un vrai delta de score non nul — jamais pour un score inchangé.
Serveur MCP
POST /api/mcp
Un serveur Model Context Protocol léger (JSON-RPC 2.0 sur simple POST HTTP) pour qu'un agent IA puisse demander « quel est mon score de visibilité IA » directement. Pointez tout client compatible MCP distant (Claude Desktop, Cursor, connecteurs ChatGPT, un agent sur mesure) vers cette URL avec un en-tête statique Authorization: Bearer — `initialize` et `tools/list` fonctionnent sans authentification (pure découverte de capacités) ; `tools/call` requiert une clé valide.
| Outil | Fait quoi | Arguments |
|---|---|---|
| list_tracked_brands | Chaque marque suivie par votre compte, avec le score de visibilité IA le plus récent de chacune. | aucun |
| get_brand_visibility | Le score de visibilité IA le plus récent et le détail par moteur (ChatGPT/Claude/Gemini/Perplexity/Grok) pour une marque suivie. | { "domain": "acme.com" } |
initialize
POST /api/mcp
{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }réponse initialize
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": { "tools": {} },
"serverInfo": { "name": "pingmybrand-mcp", "version": "1.0.0" }
}
}tools/call — get_brand_visibility
POST /api/mcp
Authorization: Bearer pmb_live_xxxxxxxxxxxxxxxx
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_brand_visibility",
"arguments": { "domain": "acme.com" }
}
}Questions, en clair
FAQ développeurs
L'API PingMyBrand est-elle incluse dans chaque plan ?
L'API REST et le serveur MCP sont disponibles sur chaque plan payant (Solo, Starter, Agency) sans coût additionnel — une clé porteur créée depuis votre compte fonctionne sur les deux. Le plan gratuit n'a pas d'accès API.
Comment une requête API PingMyBrand est-elle authentifiée ?
Chaque requête REST et MCP envoie la même clé en en-tête `Authorization: Bearer pmb_live_...`. Les méthodes `initialize` et `tools/list` de MCP fonctionnent sans authentification (découverte de capacités) ; `tools/call` requiert une clé valide, comme les endpoints REST.
Quelles sont les limites de débit de l'API PingMyBrand ?
120 requêtes par heure et par clé, suivies séparément par endpoint — épuiser /api/v1/visibility ne réduit pas votre quota /api/v1/brands ou MCP. Une réponse 429 inclut un en-tête Retry-After.
Puis-je connecter un agent IA (Claude Desktop, Cursor) directement à PingMyBrand ?
Oui — pointez tout client compatible MCP distant vers /api/mcp avec votre clé porteur. Il expose deux outils, list_tracked_brands et get_brand_visibility, limités aux seules marques que votre compte suit.
PingMyBrand notifie-t-il automatiquement mes systèmes quand le score d'une marque change ?
Oui, via POST /api/v1/webhooks — enregistrez une URL de rappel une fois et recevez un POST signé HMAC à chaque vrai changement de score non nul (jamais pour un score inchangé), réessayé jusqu'à 4 fois avec repli exponentiel en cas d'échec.
Chaque appel est limité à votre propre compte
Une clé ne peut lire que les marques que son propre compte suit — il n'y a aucun moyen d'accéder aux données d'un autre compte. Créez une clé depuis votre page de compte pour commencer.
Nouveau ici ? Lancez d'abord un scan gratuit — aucun compte requis →