Référence API

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)
Client TypeScript : guide SDK
Partenaires intégrant la visibilité : guide partenaires

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

Premiers pas avec l'API

Avant de commencer

Étape 1 — Créer une clé API

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

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

Ce que vous pouvez construire

Prochaines étapes

Référence API

Authentification

Portées

Limites de débit

Erreurs

Organisation

GET /organization

Workspaces

GET /workspaces

GET /workspaces/:id

Visibilité

GET /workspaces/:id/visibility/summary

GET /workspaces/:id/visibility/mentions

GET /workspaces/:id/visibility/competitors

Scans

POST /workspaces/:id/scans

GET /jobs/:id

Webhooks

Enregistrer un endpoint

Types d'événements

Format du payload

Vérifier les signatures

Gérer les endpoints

Jetons d'embed

POST /embed-tokens

`GET /organization`

`GET /workspaces`

`GET /workspaces/:id`

`GET /workspaces/:id/visibility/summary`

`GET /workspaces/:id/visibility/mentions`

`GET /workspaces/:id/visibility/competitors`

`POST /workspaces/:id/scans`

`GET /jobs/:id`

`POST /embed-tokens`