API REST de SEO para programadores
O mesmo motor de auditoria de 91 regras, acessível por HTTP simples. Traz a tua linguagem: curl, Node, Python, PHP, qualquer coisa que fale HTTPS. As mesmas chaves de API funcionam também com o nosso servidor MCP.
Sem cartão. Resultados em 30 segundos.
Ou cola simplesmente um URL: a mesma auditoria, sem instalar nada.
Atualizado
Autenticação por token Bearer
Cada endpoint autenticado aceita um token no cabeçalho Authorization: Authorization: Bearer ms_live_xxx. Gera uma chave em app.metricspot.com/settings/api-keys (até 10 por conta). O endpoint de auditoria anónima funciona sem chave, limitado a 1 auditoria por IP a cada 24 horas. As mesmas chaves ms_live_ funcionam para esta API REST e para o servidor MCP do MetricSpot.
curl
Endpoint anónimo, sem token. Devolve o envelope completo da auditoria em linha.
curl -X POST https://app.metricspot.com/api/public/audit \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Node (fetch)
Funciona em Node 18+, Bun, Deno e browsers modernos. Sem dependências.
const res = await fetch("https://app.metricspot.com/api/audits", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer ms_live_xxx",
},
body: JSON.stringify({ url: "https://example.com" }),
});
const audit = await res.json();Python (httpx)
requests é equivalente: troca httpx.post por requests.post.
import httpx
res = httpx.post(
"https://app.metricspot.com/api/audits",
headers={"Authorization": "Bearer ms_live_xxx"},
json={"url": "https://example.com"},
)
audit = res.json()PHP
Extensão cURL padrão, disponível em qualquer instalação de PHP desde a 4.0.
<?php
$ch = curl_init("https://app.metricspot.com/api/audits");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer ms_live_xxx",
],
CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com"]),
CURLOPT_RETURNTRANSFER => true,
]);
$audit = json_decode(curl_exec($ch), true);Seis endpoints, todo o motor de auditoria
Cada endpoint corre a mesma auditoria de 91 regras e os mesmos 11 módulos de pontuação que app.metricspot.com. JSON na entrada, JSON na saída. O endpoint anónimo de teste não precisa de chave; os outros cinco aceitam um token Bearer do teu painel.
/api/public/audit Auditoria anónima
Corre uma auditoria pontual de SEO e legibilidade para IA sobre qualquer URL público. Devolve pontuações em 11 módulos e 91 verificações, mais findings acionáveis com ligações à documentação. Limitada a 1 auditoria por IP a cada 24 horas.
/api/audits Colocar auditoria completa em fila
Coloca em fila uma auditoria completa de SEO e legibilidade para IA. Inclui Core Web Vitals do Google PageSpeed Insights e tráfego orgânico se o GA4 e o Google Search Console estiverem ligados. Responde de imediato com audit_id e status: queued.
/api/audits/:id Obter auditoria
Recupera por id uma auditoria já em fila. Devolve as pontuações dos 11 módulos (0-100), a pontuação total, cada finding com severidade e texto de recomendação, e as ligações para os relatórios HTML e PDF.
/api/audits Listar auditorias
Lista as auditorias da conta, mais recentes primeiro, desduplicadas por URL. Devolve audit_id, url, status, total_score, created_at. Limite por defeito 24, máximo 100. Paginação padrão com offset e limit.
/api/audits/:id/pdf Renderizar PDF com marca
Arranca o render de um PDF com a tua marca para uma auditoria. Combina com GET /api/pdfs/:id para obter o URL assinado de download. Os ativos de marca (logo, cores, rodapé) vêm das definições de Brands; passa brand_id para escolher uma marca específica.
/api/audits/:id/google Tráfego orgânico
Devolve o snapshot de 28 dias de tráfego orgânico para uma auditoria, se o GA4 e o Google Search Console estiverem ligados ao URL auditado. Inclui sessões, tendência diária, principais páginas de aterragem, principais queries e saúde de indexação.
API REST ou servidor MCP: qual encaixa no teu stack
As duas interfaces falam com o mesmo motor de auditoria, com as mesmas chaves e os mesmos dados. Escolhe REST quando escreves HTTP simples a partir de CI, scripts ou ferramentas no-code; escolhe MCP quando um agente de IA precisa de descobrir e encadear ferramentas por si.
| Caso de uso | Auditoria SEO manual | Outras APIs de SEO | MCP do MetricSpot | API REST do MetricSpot |
|---|---|---|---|---|
| CI/CD em cada PR | Inviável ao ritmo dos PRs | Possível mas caro por chamada, JSON frágil | Demais: o MCP brilha em agentes interativos, não em jobs headless | Um curl numa GitHub Action, comenta o delta de pontuação no PR |
| Ferramentas no-code (Zapier, n8n, Make) | Exportação e copy-paste manuais | Bloco HTTP à medida, campos mapeados à mão, frágil a mudanças de esquema | Hoje sem suporte MCP nas plataformas no-code mainstream | Bloco HTTP padrão com Bearer, resposta JSON que mapeia de forma limpa |
| Stack poliglota (Go, Ruby, Java) | Não aplicável | Um SDK por linguagem, muitas vezes mantido pela comunidade | As bibliotecas cliente MCP existem sobretudo para TypeScript e Python | Qualquer linguagem com cliente HTTPS funciona logo no primeiro dia |
| Jobs internos agendados | Horas por mês, fáceis de saltar | Preço por chamada, frequentemente por keyword ou por domínio | Funciona, mas um subprocesso stdio é desconfortável dentro do cron | HTTPS simples a partir de cron, Kubernetes CronJob ou Lambda |
| Fluxos com agentes de IA | Humano em cada ciclo | Os agentes podem chamar REST, mas precisam de wrappers escritos à mão | Pensado para isto: descrições e esquemas auto-descobertos | Possível, mas o código de cola do agente escreve-lo tu |
| PDF com marca no teu SaaS | Exportação e rebrand manuais | Normalmente só no plano mais caro | Disponível via get_audit_pdf, pensado para fluxos de agentes | POST /api/audits/:id/pdf e depois GET /api/pdfs/:id, embebe na tua UI |
Preços da API REST
A API REST está incluída em cada plano pago do MetricSpot: os mesmos créditos de auditoria, os mesmos módulos, o mesmo render de PDF. O endpoint de auditoria anónima é gratuito e funciona sem conta. As chamadas autenticadas consomem a mesma quota mensal de auditorias que vês no painel. As mesmas chaves ms_live_ funcionam para a API REST e para o servidor MCP, sem quota separada.
Free
$0/mo
Experimenta a plataforma. Sem cartão, sem compromisso.
- ·10 auditorias por mês (1 por site a cada 24h)
- ·Os dez módulos de pontuação
- ·Download PDF com a nossa marca
- ·Relatórios multilingues
Starter
$29/mo
Para freelancers com relatórios mensais.
- ·Até 5 domínios em seguimento
- ·50 auditorias por mês
- ·Relatórios PDF totalmente em marca branca
- ·Brand kit personalizado (logo, cor, rodapé)
Pro
$49/mo
Para agências, freelancers e revendedores.
- ·Tudo o do Starter
- ·Re-auditorias agendadas (semanal, quinzenal ou mensal)
- ·Domínios em seguimento ilimitados
- ·Envio de relatórios diretamente ao cliente por email
O que os programadores constroem com a API REST
Padrões concretos que vemos em equipas já em produção com a API. Cada exemplo usa os mesmos seis endpoints e o mesmo token Bearer.
- •CI/CD: audita cada preview deploy ao abrir um PR, publica um comentário com o delta de pontuação face a main, parte o build se a pontuação cair mais de 5 pontos.
- •Zapier, n8n, Make: aciona uma auditoria quando entra um lead novo no teu CRM, manda a pontuação total e os 3 findings principais para um canal de Slack e anexa o PDF com a tua marca.
- •Monitorização interna: agenda uma auditoria noturna dos teus 50 URLs principais, envia as pontuações dos módulos para um painel Grafana e alerta quando uma categoria desce.
- •SaaS de marca branca: coloca uma auditoria em fila a pedido do utilizador, renderiza o PDF com a tua marca e embebe os findings JSON na tua própria UI, sem alojares o motor de auditoria.
- •Gates de QA: bloqueia um deploy se o módulo de legibilidade para IA descer abaixo do limite combinado com o cliente, com as regras falhadas no log de build.
- •Reporting: corre GET /api/audits/:id/google depois de cada auditoria para entregar um único PDF que combina findings técnicos com tráfego orgânico de 28 dias.
Escrever HTTP simples a partir de um script ou de um runner de CI é um caminho. Se conduzes a auditoria a partir de um agente de IA (Claude Code, Cursor, ChatGPT, Gemini), o nosso servidor MCP de SEO expõe as mesmas seis ferramentas sobre Model Context Protocol com esquemas auto-descobertos: o mesmo motor, as mesmas chaves, sem código de cola.
Perguntas frequentes
A API REST é gratuita?
O endpoint de auditoria anónima (POST /api/public/audit) é gratuito e não requer conta, limitado a 1 auditoria por IP a cada 24 horas. Os endpoints autenticados estão incluídos em todos os planos MetricSpot, incluindo o Free (10 auditorias por mês). Não há preço separado para a API nem sobretaxa por chamada: as chamadas à API consomem a mesma quota de auditorias que vês no painel.
Qual a diferença para o servidor MCP?
O mesmo motor de auditoria, as mesmas 91 regras, os mesmos 11 módulos, as mesmas chaves Bearer. A API REST é HTTP simples para pessoas que escrevem código: curl, fetch, requests, o que for. O servidor MCP fala Model Context Protocol para que agentes de IA (Claude Code, Cursor, ChatGPT, Gemini) descubram automaticamente ferramentas, esquemas e autenticação. Usa REST para CI, scripts e no-code; usa MCP para fluxos com agentes.
Posso usá-la com ferramentas no-code como o Zapier?
Sim. Qualquer plataforma no-code com um bloco HTTP genérico funciona: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (módulo HTTP), Pipedream, Retool. Coloca o URL em https://app.metricspot.com/api/audits, método POST, adiciona Authorization: Bearer ms_live_xxx aos cabeçalhos e envia {"url": "https://example.com"} como JSON. A resposta mapeia limpamente em todas as plataformas testadas.
Que linguagens têm SDK oficial?
Nenhuma ainda. Só precisas de um cliente HTTPS e de parsing de JSON, e qualquer linguagem moderna já traz isso. Um SDK fino em JavaScript e TypeScript está na roadmap; até lá, os quatro exemplos de código acima cobrem cerca de 90% das integrações que vemos. Se quiseres um SDK numa linguagem específica, abre uma issue em github.com/MetricSpot.
Como me autentico?
Envia Authorization: Bearer ms_live_xxx em cada chamada autenticada. Os tokens têm o prefixo ms_live_ e são mostrados uma única vez no momento da criação; o painel guarda apenas um hash. Trata-os como qualquer outro segredo: nunca os faças commit, roda-os se forem expostos, usa uma chave por integração para revogar individualmente. O painel limita cada conta a 10 chaves ativas.
De onde vêm as chaves de API?
Gera-as em app.metricspot.com/settings/api-keys depois de te inscreveres em qualquer plano, incluindo o Free. Cada chave é mostrada apenas uma vez; copia-a para o teu cofre de segredos de imediato. As mesmas chaves funcionam para a API REST e para o servidor MCP do MetricSpot, por isso só geres um conjunto de credenciais para os dois caminhos de integração.
Os dados são os mesmos que no painel do MetricSpot?
Sim. Cada endpoint passa pelo mesmo motor de auditoria que move app.metricspot.com: as mesmas 91 regras em 11 módulos, as mesmas severidades, os mesmos textos de recomendação. O PDF de POST /api/audits/:id/pdf é o mesmo que descarregas a partir do painel. O tráfego orgânico vem das mesmas ligações ao GA4 e ao Google Search Console que autorizaste na tua conta.
Quais são os limites de uso?
O endpoint anónimo está limitado a 1 auditoria por IP a cada 24 horas. Os endpoints autenticados consomem a quota mensal do teu plano: o Free é 10 por mês (1 por site a cada 24 horas), o Starter é 50 por mês, o Pro é ilimitado. Não há rate limit por segundo para além do que o pipeline de auditoria consegue absorver; se colocares dezenas em fila ao mesmo tempo, são processadas por ordem.
Deixa de escrever relatórios de SEO à mão.
Corre uma auditoria, marca o PDF, envia ao cliente. Em cinco minutos.
Começa a tua primeira auditoria