SDK TypeScript

Le package @mencionai/sdk est le moyen le plus simple d'appeler l'API MencionAI depuis Node.js, des fonctions serverless ou tout backend TypeScript/JavaScript.

Installation

pnpm add @mencionai/sdk

npm install @mencionai/sdk

Démarrage rapide

import { MencionAiClient } from '@mencionai/sdk';

const client = new MencionAiClient({
  apiKey: process.env.MENCIONAI_API_KEY!,
});

const org = await client.getOrganization();
console.log(org.name, org.plan);

const { workspaces } = await client.listWorkspaces();

if (workspaces[0]) {
  const summary = await client.getVisibilitySummary(workspaces[0].id);
  console.log(summary.brand_name, summary.total_mentions, 'mentions');
}

L'URL de base par défaut est https://www.mencionai.com/api/v1. Remplacez-la si nécessaire :

const client = new MencionAiClient({
  apiKey: process.env.MENCIONAI_API_KEY!,
  baseUrl: 'https://www.mencionai.com/api/v1',
});

Obtenir votre clé API

Connectez-vous à MencionAI.
Allez dans Paramètres → Clés API.
Créez une clé et stockez-la dans MENCIONAI_API_KEY (ou votre gestionnaire de secrets).

N'utilisez jamais de clés API dans le code navigateur — appelez toujours l'API depuis votre serveur.

Méthodes

Organisation et workspaces

await client.getOrganization();
await client.listWorkspaces();
await client.getWorkspace(42);

Visibilité

const summary = await client.getVisibilitySummary(42);
// summary.prompts_tracked, summary.total_mentions, summary.total_citations, …

Scans

Mettez en file un scan avec une clé d'idempotence unique (ex. UUID ou votre propre id de déduplication) :

const { job_id, status } = await client.enqueueScan(42, 'scan-run-2026-07-06-001');

let job = await client.getJob(job_id);
while (job.status === 'pending' || job.status === 'processing') {
  await new Promise((r) => setTimeout(r, 3000));
  job = await client.getJob(job_id);
}

console.log('Scan terminé :', job.status);

Webhooks

const { endpoints } = await client.listWebhooks();

const endpoint = await client.createWebhook({
  url: 'https://votre-app.com/webhooks/mencionai',
  events: ['visibility.scan.completed'],
});

// Enregistrez endpoint.secret — affiché uniquement à la création
console.log('Webhook secret:', endpoint.secret);

Jetons d'embed

const { token, expires_in } = await client.createEmbedToken({
  workspace_id: 42,
  ttl_sec: 3600,
});

const iframeUrl = `https://www.mencionai.com/embed/v1/workspaces/42/summary?token=${token}`;

Gestion des erreurs

Les requêtes échouées lancent MencionAiError :

import { MencionAiClient, MencionAiError } from '@mencionai/sdk';

try {
  await client.getOrganization();
} catch (err) {
  if (err instanceof MencionAiError) {
    console.error(err.code);       // ex. RATE_LIMIT_EXCEEDED
    console.error(err.status);     // statut HTTP
    console.error(err.requestId);  // pour le support
  }
  throw err;
}

Types TypeScript

Le SDK exporte des types pour les réponses courantes :

import type { Workspace, VisibilitySummary } from '@mencionai/sdk';

Version de l'API

Le SDK cible la version d'API 2026-07-01. Consultez la référence API ou la spécification OpenAPI pour les formes complètes requête/réponse.