TypeScript SDK

The @mencionai/sdk package is the easiest way to call the MencionAI API from Node.js, serverless functions, or any TypeScript/JavaScript backend.

Install

pnpm add @mencionai/sdk

npm install @mencionai/sdk

Quick start

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');
}

The default base URL is https://www.mencionai.com/api/v1. Override it if needed:

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

Get your API key

Sign in to MencionAI.
Go to Settings → API Keys.
Create a key and store it in MENCIONAI_API_KEY (or your secret manager).

Never use API keys in browser code — always call the API from your server.

Methods

Organization & workspaces

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

Visibility

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

Scans

Enqueue a scan with a unique idempotency key (e.g. UUID or your own dedupe id):

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 finished:', job.status);

Webhooks

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

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

// Save endpoint.secret — shown only on create
console.log('Webhook secret:', endpoint.secret);

Embed tokens

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}`;

Error handling

Failed requests throw MencionAiError:

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

try {
  await client.getOrganization();
} catch (err) {
  if (err instanceof MencionAiError) {
    console.error(err.code);       // e.g. RATE_LIMIT_EXCEEDED
    console.error(err.status);     // HTTP status
    console.error(err.requestId);  // for support
  }
  throw err;
}

TypeScript types

The SDK exports types for common responses:

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

API version

The SDK targets API version 2026-07-01. See the API reference or OpenAPI spec for full request/response shapes.