API

API publique v1

Données de visibilité et orchestration des scans pour votre organisation.

Premiers pas avec l'API

Utilisez l'API MencionAI pour lire les données de visibilité de marque et déclencher des scans depuis vos applications, tableaux de bord ou automatisations.

Avant de commencer

Vous avez besoin d'un compte MencionAI avec au moins un workspace (marque/domaine) configuré.

Étape 1 — Créer une clé API

  1. Connectez-vous à MencionAI.
  2. Ouvrez Paramètres → Clés API.
  3. Cliquez sur Créer une clé API et copiez la valeur immédiatement. Elle n'est affichée qu'une seule fois.

Les clés ressemblent à mak_live_… (production) ou mak_test_… (sandbox).

Stockez la clé dans un gestionnaire de secrets ou une variable d'environnement — ne la commitez jamais dans git et ne l'exposez pas côté client.

Étape 2 — Faire votre première requête

curl -s \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  https://www.mencionai.com/api/v1/organization

Exemple de réponse :

{
  "id": 1,
  "name": "Acme Inc",
  "plan": "Growth",
  "subscription_status": "active"
}

Étape 3 — Lister les workspaces et lire la visibilité

# Lister les workspaces
curl -s \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  https://www.mencionai.com/api/v1/workspaces

# Résumé de visibilité pour le workspace 42
curl -s \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  https://www.mencionai.com/api/v1/workspaces/42/visibility/summary

Ce que vous pouvez construire

| Objectif | Commencez ici | |----------|---------------| | Tableau de bord BI interne | GET /workspaces/:id/visibility/summary | | Alerte à la fin d'un scan | Webhooks + visibility.scan.completed | | Graphique intégré dans votre produit | Jetons d'embed → iframe | | Re-scans automatisés | POST /workspaces/:id/scans + polling GET /jobs/:id |

Prochaines étapes

  • Référence complète sur la page API (explorateur OpenAPI interactif inclus)
  • Serveur MCP pour Cursor / Claude Desktop : guide MCP
  • Client TypeScript : guide SDK
  • Partenaires intégrant la visibilité : guide partenaires

MencionAI MCP

Utilisez le serveur MCP MencionAI pour lire la visibilité dans les recherches IA et enfiler des scans depuis Cursor, Claude Desktop ou tout client MCP.

Le MCP est un adaptateur mince sur l’API publique v2. Il utilise votre clé API et les mêmes scopes que l’API HTTP. Les tools ne parlent pas directement à la base de données.

Avant de commencer

  1. Créez une clé sous Paramètres → Clés API (mak_live_… ou mak_test_…). L’écran propose aussi des snippets d’installation MCP.
  2. Installez Node.js 20+ (pour le stdio local).
  3. Accordez les scopes nécessaires :
    • organization:read + workspaces:read — lister les workspaces et lire la visibilité
    • jobs:read + scopes d’écriture/scan — enfiler / attendre des scans
    • visibility:answers:read — uniquement pour get_visibility_responses (extraits de réponses)

Ne passez jamais la clé API comme argument de tool. Placez-la dans l’environnement du processus MCP (stdio) ou en Authorization: Bearer (hébergé).

Stdio local (bon pour démarrer)

pnpm add -g @mencionai/mcp
# ou : npx -y @mencionai/mcp

Cursor (.cursor/mcp.json) :

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Optionnel : définissez MENCIONAI_API_BASE_URL pour une base URL v2 hors production.

MCP hébergé (préféré pour les agents en production)

Utilisez l’endpoint Streamable HTTP hébergé pour les rate limits et la télémétrie produit. Le stdio sur les machines clients n’écrit pas d’événements d’usage.

URL : https://mcp.mencionai.com/mcp

Exemple de config distante (remplacez la clé ; la forme JSON exacte dépend du client MCP) :

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Authentifiez avec Authorization: Bearer YOUR_API_KEY. Ne passez jamais la clé comme argument de tool.

Flux préféré

Utilisez ce chemin sauf si l’utilisateur demande une tranche brute :

  1. list_workspaces
  2. get_visibility_overview
  3. explain_visibility_gaps / compare_competitors
  4. wait_for_visibility_scan quand un rafraîchissement est nécessaire (consomme le quota du plan)
  5. get_visibility_series pour les tendances

N’appelez pas les tools de visibilité « thin » (get_visibility_summary, get_visibility_mentions, get_visibility_competitors, get_visibility_coverage, get_visibility_citations) sauf si la sortie composée est insuffisante ou si l’utilisateur demande cette tranche. get_visibility_responses exige visibility:answers:read et échoue fermé sans ce scope.

Tools

| Tool | Objectif | |------|----------| | get_visibility_overview | Commencez ici — snapshot composé (summary + coverage + competitors + citations) | | compare_competitors | Classe les rivaux par mentions/citations vs la marque | | explain_visibility_gaps | Prompts où des concurrents apparaissent mais pas la marque | | wait_for_visibility_scan | Enfile + attend le scan (défaut 60s, max 120s ; consomme le quota) | | get_visibility_series | Scores quotidiens (7d | 30d | 90d) | | get_organization / list_workspaces / get_workspace | Lectures org & workspace | | get_visibility_responses | Extraits de réponses (nécessite visibility:answers:read) | | get_visibility_coverage / citations / summary / mentions / competitors | Lectures thin (power user) | | enqueue_visibility_scan / get_job | Scan manuel + poll (préférez wait_for_visibility_scan) |

Exemples de prompts

  1. Share of voice : « Avec MencionAI, ouvre mon workspace et résume où nous perdons du share face aux trois principaux concurrents sur ChatGPT. »
  2. Gaps : « Quels prompts suivis mentionnent un concurrent mais pas notre marque ? Liste les hosts rivaux. »
  3. Citations : « À partir de l’overview de visibilité, quels domaines nous citent le plus, et quelles URLs top ne sont pas notre site ? »
  4. Rescan : « Enfile un scan pour mon workspace principal, attends jusqu’à 60 secondes, puis rafraîchis l’overview. »
  5. Tendances : « Montre la série de visibilité sur 30 jours pour mon workspace principal et souligne le dernier changement de score. »

Dépannage

| Symptôme | À vérifier | |----------|------------| | 401 / non autorisé | Clé absente, révoquée ou mauvais environnement (mak_live_ vs mak_test_) | | Erreur de scope / forbidden | Il manque workspaces:read (ou les scopes d’écriture de scan) | | get_visibility_responses échoue fermé | Ajoutez visibility:answers:read à la création de la clé | | Scan lent ou rejeté | Quota du plan ; préférez wait_for_visibility_scan avec timeout ≤ 120s | | L’agent demande votre clé API | MCP mal configuré — la clé va dans env / Bearer, jamais dans les arguments |

Étapes suivantes

Référence API

L'API REST MencionAI permet d'accéder aux données d'organisation et de workspace, aux métriques de visibilité, aux scans, webhooks et jetons d'embed.

URL de base : https://www.mencionai.com/api/v1

Spécification OpenAPI : Télécharger le YAML

Toutes les requêtes nécessitent une authentification sauf indication contraire.

Authentification

Passez votre clé API dans l'en-tête Authorization :

Authorization: Bearer mak_live_xxxxxxxx

| Préfixe de clé | Usage | |---------------|-------| | mak_live_ | Données de production | | mak_test_ | Tests et développement |

Créez des clés dans le tableau de bord MencionAI sous Paramètres → Clés API.

Portées

Lors de la création d'une clé, un ensemble de portées lui est attribué. Chaque endpoint exige une portée spécifique :

| Portée | Autorise | |--------|----------| | organization:read | Lire les informations de l'organisation | | workspaces:read | Lister les workspaces et données de visibilité | | workspaces:write | Mettre en file des scans de visibilité | | jobs:read | Vérifier le statut des jobs de scan | | embed:create | Créer des jetons d'embed à courte durée | | webhooks:manage | Enregistrer et gérer les endpoints webhook |

Si une portée manque, l'API renvoie 403 avec le code MISSING_SCOPE.

Limites de débit

Les limites s'appliquent par organisation et dépendent de votre forfait :

| Forfait | Requêtes par minute | |---------|---------------------| | Free | 30 | | Starter | 60 | | Growth | 300 | | Enterprise | 1 000 |

Chaque réponse inclut :

  • X-RateLimit-Limit — limite de votre forfait
  • X-RateLimit-Remaining — requêtes restantes dans la fenêtre actuelle

En cas de dépassement, l'API renvoie 429 avec l'en-tête Retry-After (secondes avant de réessayer).

Erreurs

Les erreurs utilisent un format JSON cohérent :

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key",
    "request_id": "req_abc123"
  }
}

Codes courants :

| Code | HTTP | Signification | |------|------|---------------| | UNAUTHORIZED | 401 | Clé API manquante ou invalide | | FORBIDDEN | 403 | Portée manquante ou fonction non incluse dans votre forfait | | NOT_FOUND | 404 | Workspace ou ressource introuvable | | RATE_LIMIT_EXCEEDED | 429 | Trop de requêtes | | IDEMPOTENCY_KEY_REQUIRED | 422 | POST scan sans Idempotency-Key | | VALIDATION_ERROR | 422 | Corps ou paramètre de chemin invalide |

Incluez le request_id lors d'un contact avec le support.

Organisation

GET /organization

Renvoie le nom, le forfait et le statut d'abonnement de votre organisation.

curl -H "Authorization: Bearer VOTRE_CLE_API" \
  https://www.mencionai.com/api/v1/organization

Workspaces

Un workspace représente une marque/domaine que vous suivez dans MencionAI.

GET /workspaces

Liste tous les workspaces de votre organisation.

{
  "workspaces": [
    {
      "id": 42,
      "domain": "acme.com",
      "brand_name": "Acme",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

GET /workspaces/:id

Renvoie les métadonnées d'un workspace.

Visibilité

Tous les endpoints de visibilité exigent workspaces:read.

GET /workspaces/:id/visibility/summary

Métriques globales : mentions, citations, prompts suivis, fournisseurs, dernière synchronisation.

GET /workspaces/:id/visibility/mentions

Mentions regroupées par prompt/mot-clé.

GET /workspaces/:id/visibility/competitors

Statistiques de visibilité des concurrents (mentions et citations par hôte).

Scans

Déclenchez un nouveau scan de visibilité IA pour un workspace.

POST /workspaces/:id/scans

Exige workspaces:write et l'en-tête Idempotency-Key (unique par requête logique). Réutiliser la même clé avec le même corps renvoie la réponse d'origine au lieu de remettre en file.

curl -X POST \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Idempotency-Key: scan-2026-07-06-acme-001" \
  https://www.mencionai.com/api/v1/workspaces/42/scans

Réponse (202) :

{
  "job_id": 901,
  "status": "pending"
}

GET /jobs/:id

Interrogez le statut du job. Exige jobs:read.

{
  "id": 901,
  "type": "ai_scan",
  "status": "completed",
  "created_at": "2026-07-06T12:00:00.000Z"
}

Valeurs de statut : pending, processing, completed, failed.

Flux typique : mettre en file → interroger toutes les quelques secondes jusqu'à completed → récupérer le résumé de visibilité mis à jour.

Webhooks

Recevez des callbacks HTTP lors d'événements dans votre organisation. Disponible à partir du forfait Starter.

Enregistrer un endpoint

curl -X POST \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-app.com/webhooks/mencionai",
    "events": ["visibility.scan.completed"]
  }' \
  https://www.mencionai.com/api/v1/webhooks

La réponse inclut un secret — enregistrez-le immédiatement. Il sert à vérifier les signatures.

Types d'événements

| Événement | Déclenchement | |-----------|---------------| | visibility.scan.enqueued | Un scan a été accepté | | visibility.scan.completed | Un scan s'est terminé avec succès | | report.generated | Un rapport est prêt |

Format du payload

{
  "id": "evt_uuid",
  "type": "visibility.scan.completed",
  "created_at": "2026-07-06T12:05:00.000Z",
  "data": {
    "workspace_id": 42,
    "job_id": 901,
    "result_id": 555
  }
}

Vérifier les signatures

Chaque livraison inclut :

X-MencionAI-Signature: t=1710000000,v1=abc123...

Vérifiez en calculant HMAC-SHA256 sur {timestamp}.{corps_brut} avec le secret de l'endpoint, puis comparez à v1.

Gérer les endpoints

| Méthode | Chemin | Action | |---------|--------|--------| | GET | /webhooks | Lister les endpoints | | GET | /webhooks/:id | Obtenir un endpoint | | PATCH | /webhooks/:id | Mettre à jour l'URL ou les événements | | DELETE | /webhooks/:id | Désactiver l'endpoint |

Jetons d'embed

Affichez la visibilité MencionAI dans votre produit via une iframe sécurisée.

POST /embed-tokens

Exige embed:create.

curl -X POST \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": 42, "ttl_sec": 3600 }' \
  https://www.mencionai.com/api/v1/embed-tokens

{
  "token": "met_...",
  "expires_in": 3600,
  "workspace_id": 42
}

Chargez dans une iframe :

https://www.mencionai.com/embed/v1/workspaces/42/summary?token=met_...

Les jetons sont à courte durée. Créez-en un nouveau côté serveur à l'expiration — n'exposez pas votre clé API dans le navigateur.

Consultez le guide partenaires pour les bonnes pratiques d'intégration.