API Reference

Fetch visibility data

const API_KEY = "mtv_live_your_key";
const BASE = "https://mentova.ai/api/v1";

const get = (path) =>
  fetch(`${BASE}${path}`, { headers: { "X-API-Key": API_KEY } }).then(r => r.json());

// List brands
const { data: brands } = await get("/brands");
const brandId = brands[0].id;

// Visibility — last 30 days
const { data: visibility } = await get(`/brands/${brandId}/visibility?days=30`);
console.log(visibility.mentionRate, visibility.shareOfVoice);

// Competitors leaderboard
const { data: competitors } = await get(`/brands/${brandId}/competitors`);

// Open opportunities
const { data: opps } = await get(`/brands/${brandId}/opportunities?status=open`);

Manage audience avatars

// Create an audience avatar
const { data: avatar } = await fetch(`${BASE}/brands/${brandId}/avatars`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Sarah, CMO",
    sector: "SaaS B2B",
    role: "Chief Marketing Officer",
    objectives: "Grow brand share of voice in AI search results",
    isDefault: true,
  }),
}).then(r => r.json());

// List avatars
const { data: avatars } = await fetch(`${BASE}/brands/${brandId}/avatars`, {
  headers: { "X-API-Key": API_KEY },
}).then(r => r.json());

Launch a campaign

// Get topics first
const { data: topics } = await get(`/brands/${brandId}/topics`);

// Launch campaign on first topic
const { data: campaign } = await fetch(`${BASE}/brands/${brandId}/campaigns`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ topicId: topics[0].id }),
}).then(r => r.json());

// Poll status
let status = campaign.status;
while (status === "running") {
  await new Promise(r => setTimeout(r, 5000));
  const { data } = await get(`/brands/${brandId}/campaigns/${campaign.id}`);
  status = data.status;
}

// Fetch prompts when done
const { data: prompts } = await get(`/brands/${brandId}/prompts?status=mentioned`);