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

Connectez-vous à MencionAI.
Ouvrez Paramètres → Clés API.
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

Les guides de connexion Cursor, Claude, Codex, Antigravity et n8n sont sur le hub MCP.

URLs courtes pour les agents (redirection vers ce site) : docs.mencionai.com/mcp.

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.

API publique v1