API pública v1

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

1. Entre em MencionAI.
2. Abra Configurações → Chaves de API.
3. 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)
• Cliente TypeScript: guia do SDK
• Parceiros incorporando visibilidade: guia de parceiros

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.

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.