Primeiros passos com a API

Use a API MencionAI para ler dados de visibilidade de marca e disparar scans a partir dos seus apps, dashboards ou automações.

Antes de começar

Você precisa de uma conta MencionAI com pelo menos um workspace (marca/domínio) configurado.

Passo 1 — Criar uma chave de API

Entre em MencionAI.
Abra Configurações → Chaves de API.
Clique em Criar chave de API e copie o valor imediatamente. Ele é exibido apenas uma vez.

As chaves têm o formato mak_live_… (produção) ou mak_test_… (sandbox).

Guarde a chave em um gerenciador de segredos ou variável de ambiente — nunca faça commit no git nem exponha em código client-side.

Passo 2 — Fazer sua primeira requisição

curl -s \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  https://www.mencionai.com/api/v1/organization

Exemplo de resposta:

{
  "id": 1,
  "name": "Acme Inc",
  "plan": "Growth",
  "subscription_status": "active"
}

Passo 3 — Listar workspaces e ler visibilidade

# Listar workspaces
curl -s \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  https://www.mencionai.com/api/v1/workspaces

# Resumo de visibilidade do workspace 42
curl -s \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  https://www.mencionai.com/api/v1/workspaces/42/visibility/summary

O que você pode construir

| Objetivo | Comece aqui | |----------|-------------| | Dashboard interno de BI | GET /workspaces/:id/visibility/summary | | Alerta quando um scan terminar | Webhooks + visibility.scan.completed | | Gráfico incorporado no seu produto | Tokens de embed → iframe | | Re-scans automatizados | POST /workspaces/:id/scans + polling em GET /jobs/:id |

Próximos passos

Referência completa na página da API (inclui explorador OpenAPI interativo)
Servidor MCP para Cursor / Claude Desktop: guia MCP
Cliente TypeScript: guia do SDK
Parceiros incorporando visibilidade: guia de parceiros

MencionAI MCP

Use o servidor MCP da MencionAI para ler visibilidade em buscas de IA e enfileirar scans no Cursor, Claude Desktop ou qualquer cliente MCP.

O MCP é um adaptador fino sobre a API pública v2. Usa sua chave de API e os mesmos escopos do HTTP. As tools não falam com o banco diretamente.

Antes de começar

Crie uma chave em Configurações → Chaves de API (mak_live_… ou mak_test_…). A tela também tem snippets de instalação do MCP.
Instale Node.js 20+ (para stdio local).
Conceda os escopos necessários:
- organization:read + workspaces:read — listar workspaces e ler visibilidade
- jobs:read + escopos de escrita/scan — enfileirar / aguardar scans
- visibility:answers:read — só se precisar de get_visibility_responses (trechos de resposta)

Nunca passe a chave de API como argumento de tool. Coloque-a no ambiente do processo MCP (stdio) ou em Authorization: Bearer (hospedado).

Stdio local (bom para começar)

pnpm add -g @mencionai/mcp
# ou: npx -y @mencionai/mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Opcional: defina MENCIONAI_API_BASE_URL para um base URL v2 não produtivo.

MCP hospedado (preferido para agentes em produção)

Use o endpoint Streamable HTTP hospedado quando quiser rate limits e telemetria de produto. Stdio em máquinas de clientes não grava eventos de uso.

URL: https://mcp.mencionai.com/mcp

Exemplo de config remota (substitua a chave; o JSON exato depende do cliente MCP):

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Autentique com Authorization: Bearer YOUR_API_KEY. Nunca passe a chave como argumento de tool.

Fluxo preferido

Para dúvidas de how-to / setup, chame list_docs e depois get_doc (api, sdk, whitelabel, ars, mcp, llms) antes de inventar respostas. Tools de docs não precisam de API key.

Para dados de visibilidade, use este caminho, salvo se o usuário pedir um recorte cru:

list_workspaces
get_visibility_overview
explain_visibility_gaps / compare_competitors
wait_for_visibility_scan quando precisar atualizar (consome cota do plano)
get_visibility_series para tendências

Não chame tools finas de visibilidade (get_visibility_summary, get_visibility_mentions, get_visibility_competitors, get_visibility_coverage, get_visibility_citations) a menos que a saída composta seja insuficiente ou o usuário peça esse recorte. get_visibility_responses exige visibility:answers:read e falha fechado sem ele.

Tools

| Tool | Propósito | |------|-----------| | list_docs / get_doc | Guias públicos (API, SDK, whitelabel, ARS, MCP, llms.txt) | | get_visibility_overview | Comece aqui — snapshot composto (summary + coverage + competitors + citations) | | compare_competitors | Rankeia rivais por mentions/citations vs a marca | | explain_visibility_gaps | Prompts onde concorrentes aparecem e a marca não | | wait_for_visibility_scan | Enfileira + espera o scan (padrão 60s, máx. 120s; consome cota) | | get_visibility_series | Scores diários incluindo ARS (7d | 30d | 90d) | | get_traffic_summary / get_traffic_series | Visitas de indicação de IA via snippet (ChatGPT/Gemini/…) | | get_organization / list_workspaces / get_workspace | Leituras de org e workspace | | get_visibility_responses | Trechos de resposta (exige visibility:answers:read) | | get_visibility_coverage / citations / summary / mentions / competitors | Leituras finas (power user) | | enqueue_visibility_scan / get_job | Scan manual + poll (prefira wait_for_visibility_scan) |

Exemplos de prompts

Share of voice: “Com a MencionAI, abra meu workspace e resuma onde perdemos share frente aos três principais concorrentes no ChatGPT.”
Gaps: “Quais prompts monitorados mencionam um concorrente mas não a nossa marca? Liste os hosts rivais.”
Citações: “A partir do overview de visibilidade, quais domínios mais nos citam e quais URLs top não são do nosso site?”
Rescan: “Enfileire um scan do meu workspace principal, espere até 60 segundos e atualize o overview.”
Tendências: “Mostre a série de 30 dias do meu workspace principal e destaque a mudança mais recente do score.”

Solução de problemas

| Sintoma | O que verificar | |---------|-----------------| | 401 / não autorizado | Chave ausente, revogada ou ambiente errado (mak_live_ vs mak_test_) | | Erro de escopo / forbidden | Falta workspaces:read (ou escopos de escrita de scan) | | get_visibility_responses falha fechado | Inclua visibility:answers:read ao criar a chave | | Scan lento ou rejeitado | Cota do plano; prefira wait_for_visibility_scan com timeout ≤ 120s | | O agente pede a chave de API | MCP mal configurado — a chave vai no env / Bearer, nunca nos argumentos |

Próximos passos

Referência da API

A API REST da MencionAI permite acessar dados de organização e workspace, métricas de visibilidade, scans, webhooks e tokens de embed.

URL base: https://www.mencionai.com/api/v1

Especificação OpenAPI: Baixar YAML

Todas as requisições exigem autenticação, salvo indicação contrária.

Autenticação

Envie sua chave de API no cabeçalho Authorization:

Authorization: Bearer mak_live_xxxxxxxx

| Prefixo da chave | Uso | |------------------|-----| | mak_live_ | Dados de produção | | mak_test_ | Testes e desenvolvimento |

Crie chaves no painel MencionAI em Configurações → Chaves de API.

Escopos

Ao criar uma chave, ela recebe um conjunto de escopos. Cada endpoint exige um escopo específico:

| Escopo | Permite | |--------|---------| | organization:read | Ler informações da organização | | workspaces:read | Listar workspaces e dados de visibilidade | | workspaces:write | Enfileirar scans de visibilidade | | jobs:read | Verificar status de jobs de scan | | embed:create | Criar tokens de embed de curta duração | | webhooks:manage | Registrar e gerenciar endpoints de webhook |

Se um escopo estiver ausente, a API retorna 403 com código MISSING_SCOPE.

Limites de taxa

Os limites se aplicam por organização e dependem do seu plano:

| Plano | Requisições por minuto | |-------|------------------------| | Free | 30 | | Starter | 60 | | Growth | 300 | | Enterprise | 1.000 |

Toda resposta inclui:

X-RateLimit-Limit — limite do seu plano
X-RateLimit-Remaining — requisições restantes na janela atual

Ao exceder o limite, a API retorna 429 com cabeçalho Retry-After (segundos até poder tentar novamente).

Erros

Os erros usam um formato JSON consistente:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key",
    "request_id": "req_abc123"
  }
}

Códigos comuns:

| Código | HTTP | Significado | |--------|------|-------------| | UNAUTHORIZED | 401 | Chave de API ausente ou inválida | | FORBIDDEN | 403 | Escopo ausente ou recurso não disponível no plano | | NOT_FOUND | 404 | Workspace ou recurso não encontrado | | RATE_LIMIT_EXCEEDED | 429 | Muitas requisições | | IDEMPOTENCY_KEY_REQUIRED | 422 | POST de scan sem Idempotency-Key | | VALIDATION_ERROR | 422 | Corpo ou parâmetro de path inválido |

Inclua o request_id ao contatar o suporte.

Organização

`GET /organization`

Retorna nome, plano e status da assinatura da sua organização.

curl -H "Authorization: Bearer SUA_CHAVE_API" \
  https://www.mencionai.com/api/v1/organization

Workspaces

Um workspace representa uma marca/domínio que você acompanha na MencionAI.

`GET /workspaces`

Lista todos os workspaces da sua organização.

{
  "workspaces": [
    {
      "id": 42,
      "domain": "acme.com",
      "brand_name": "Acme",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

`GET /workspaces/:id`

Retorna metadados de um workspace.

Visibilidade

Todos os endpoints de visibilidade exigem workspaces:read.

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

Métricas gerais: menções, citações, prompts monitorados, provedores, última sincronização.

Na API pública v2, também retorna ars_score (AI Recommendation Score, 0–100) e ars_components (detalhamento). Scores não existem na v1. Veja o guia do ARS.

`GET /workspaces/:id/visibility/series`

Série diária de scores (7d | 30d | 90d). Pontos incluem ai_score / visibility_score legados e ars_score (tendência principal).

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

Menções agrupadas por prompt/palavra-chave.

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

Estatísticas de visibilidade de concorrentes (menções e citações por host).

Scans

Dispare um novo scan de visibilidade em IA para um workspace.

`POST /workspaces/:id/scans`

Exige workspaces:write e o cabeçalho Idempotency-Key (único por requisição lógica). Reutilizar a mesma chave com o mesmo corpo retorna a resposta original em vez de enfileirar novamente.

curl -X POST \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Idempotency-Key: scan-2026-07-06-acme-001" \
  https://www.mencionai.com/api/v1/workspaces/42/scans

Resposta (202):

{
  "job_id": 901,
  "status": "pending"
}

`GET /jobs/:id`

Consulte o status do job. Exige jobs:read.

{
  "id": 901,
  "type": "ai_scan",
  "status": "completed",
  "created_at": "2026-07-06T12:00:00.000Z"
}

Valores de status: pending, processing, completed, failed.

Fluxo típico: enfileirar scan → consultar a cada poucos segundos até completed → buscar resumo de visibilidade atualizado.

Webhooks

Receba callbacks HTTP quando eventos ocorrerem na sua organização. Disponível nos planos Starter e superiores.

Registrar um endpoint

curl -X POST \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-app.com/webhooks/mencionai",
    "events": ["visibility.scan.completed"]
  }' \
  https://www.mencionai.com/api/v1/webhooks

A resposta inclui um secret — salve imediatamente. Você precisa dele para verificar assinaturas.

Tipos de evento

| Evento | Quando dispara | |--------|----------------| | visibility.scan.enqueued | Um scan foi aceito | | visibility.scan.completed | Um scan terminou com sucesso | | report.generated | Um relatório está pronto |

Formato do 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
  }
}

Verificar assinaturas

Cada entrega inclui:

X-MencionAI-Signature: t=1710000000,v1=abc123...

Verifique calculando HMAC-SHA256 sobre {timestamp}.{corpo_bruto} com o secret do endpoint e compare com v1.

Gerenciar endpoints

| Método | Path | Ação | |--------|------|------| | GET | /webhooks | Listar endpoints | | GET | /webhooks/:id | Obter um endpoint | | PATCH | /webhooks/:id | Atualizar URL ou eventos | | DELETE | /webhooks/:id | Desativar endpoint |

Tokens de embed

Exiba a visibilidade MencionAI dentro do seu produto via iframe seguro.

`POST /embed-tokens`

Exige embed:create.

curl -X POST \
  -H "Authorization: Bearer SUA_CHAVE_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
}

Carregue em um iframe:

https://www.mencionai.com/embed/v1/workspaces/42/summary?token=met_...

Os tokens são de curta duração. Crie um novo no servidor quando o anterior expirar — não exponha sua chave de API no navegador.

Veja o guia de parceiros para boas práticas de incorporação.

API pública v1

Primeiros passos com a API

Antes de começar

Passo 1 — Criar uma chave de API

Passo 2 — Fazer sua primeira requisição

Passo 3 — Listar workspaces e ler visibilidade

O que você pode construir

Próximos passos

MencionAI MCP

Antes de começar

Stdio local (bom para começar)

MCP hospedado (preferido para agentes em produção)

Fluxo preferido

Tools

Exemplos de prompts

Solução de problemas

Próximos passos

Referência da API

Autenticação

Escopos

Limites de taxa

Erros

Organização

GET /organization

Workspaces

GET /workspaces

GET /workspaces/:id

Visibilidade

GET /workspaces/:id/visibility/summary

GET /workspaces/:id/visibility/series

GET /workspaces/:id/visibility/mentions

GET /workspaces/:id/visibility/competitors

Scans

POST /workspaces/:id/scans

GET /jobs/:id

Webhooks

Registrar um endpoint

Tipos de evento

Formato do payload

Verificar assinaturas

Gerenciar endpoints

Tokens de embed

POST /embed-tokens

`GET /organization`

`GET /workspaces`

`GET /workspaces/:id`

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

`GET /workspaces/:id/visibility/series`

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

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

`POST /workspaces/:id/scans`

`GET /jobs/:id`

`POST /embed-tokens`