API REST de SEO para programadores

A API de SEO da MetricSpot corre a mesma auditoria de 154 regras (on-page + legibilidade para IA) que o nosso painel, por HTTP simples. Traz a tua linguagem: curl, Node, Python, PHP, qualquer coisa que fale HTTPS. As mesmas chaves Bearer funcionam também com o nosso servidor MCP.

Experimenta a API de SEO agora mesmo, sem registo, sem token, só curl:

curl -s -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq .total_score

Sem cartão. Resultados em 30 segundos.

Testa cada chamada a partir do navegador

Referência OpenAPI 3.1 com exemplos de pedido em direto para os 12 endpoints.

Abrir referência da API →

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). As chamadas autenticadas com token requerem o plano Pro e consomem a tua quota de 5.000 por mês. 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);

Doze endpoints, todo o motor de auditoria

Cada endpoint corre a mesma auditoria de 154 regras e os mesmos 15 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 onze aceitam um token Bearer do teu painel.

POST /api/public/audit
Sem auth

Auditoria anónima

Corre uma auditoria pontual de SEO e legibilidade para IA sobre qualquer URL público. Devolve pontuações em 15 módulos e 154 verificações, mais findings acionáveis. Sem conta. Limitada a 1 auditoria por IP a cada 24 horas.

POST /api/audits
Bearer necessário

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.

GET /api/audits/:id
Bearer necessário

Obter auditoria

Recupera por id uma auditoria já em fila. Devolve as pontuações dos 15 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.

GET /api/audits
Bearer necessário

Listar auditorias

Lista as auditorias da conta, mais recentes primeiro, desduplicadas por URL. Devolve audit_id, url, status, total_score, has_ga, has_gsc, created_at. Limite por defeito 24, máximo 100.

DELETE /api/audits/:id
Bearer necessário

Apagar auditorias por URL

Apaga todas as auditorias cujo URL coincide com o do audit_id indicado. Devolve 204 em caso de sucesso.

PATCH /api/audits/reorder
Bearer necessário

Reordenar auditorias

Define a posição de exibição das auditorias no dashboard. Body: { "url_order": ["https://a.com", "https://b.com", ...] } (máx. 200 URLs). Devolve 204.

GET /api/audits/history
Bearer necessário

Histórico de auditorias

Devolve até 50 auditorias históricas para um URL. Útil para acompanhar a evolução da pontuação ao longo do tempo. Query: ?url=<url-codificado>.

GET /api/audits/usage
Bearer necessário

Consumo de auditorias

Devolve a quota de auditorias do mês corrente: audits_remaining, audits_used, plan_limit, reset_at.

POST /api/audits/:id/pdf
Bearer necessário

Renderizar PDF com marca

Arranca o render de um PDF com marca para uma auditoria concluída. Body: { "language": "en", "brand_id": 42 } (ambos opcionais). Devolve 201 com { pdf: { id, status: "pending" } }. Combina com GET /api/pdfs/:id para fazer polling.

GET /api/pdfs/:id
Bearer necessário

Verificar estado do PDF

Devolve { pdf: { id, status, download_url } }. Se Accept: application/pdf e o estado for ready, devolve diretamente o binário do PDF.

GET /api/pdfs/:id/download
Bearer necessário

Descarregar PDF

Download direto de um PDF concluído com Content-Disposition: attachment.

GET /api/audits/:id/report
Bearer necessário

Pré-visualizar relatório HTML

Renderiza o relatório de auditoria como HTML com marca (o mesmo template a partir do qual o PDF é gerado). Útil para incorporar num iframe de portal de cliente antes de descarregar o PDF. Query: ?lang=en&brand_id=42.

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

Como a API de SEO da MetricSpot se compara à DataForSEO e à Serpstack

DataForSEO é um marketplace completo de dados SEO; Serpstack é uma API de scraping de SERPs; MetricSpot é uma API focada em auditoria on-page + legibilidade para IA. Mesmo trio de letras, forma de valor distinta. Escolhe a que combina com o trabalho que estás mesmo a fazer.

O que comparas DataForSEO Serpstack API de SEO MetricSpot
Trabalho principal que resolve Marketplace massivo de dados: SERPs, keywords, backlinks, on-page Faz scraping do HTML das SERPs do Google a pedido Corre uma auditoria completa on-page + legibilidade para IA sobre uma URL, devolve scores e correções
O que recebes de uma chamada JSON específico do endpoint; a auditoria on-page devolve ~30 tags/problemas Resultados SERP, anúncios, queries relacionadas, sem avaliação on-page Score total, 15 módulos (0-100), cada finding das 154 regras, severidade e texto de recomendação
Modelo de preços Por chamada, varia por endpoint ($0,0006-$0,002 cada), saldo pré-pago Mensal por escalões: 100 grátis / $30 por 5K / até $200 por 50K SERPs Fixo $49/mês Pro = 5.000 chamadas API, sem matemática por chamada
Endpoint de teste anónimo Não, requer registo + depósito de $1 100 chamadas/mês grátis com registo + access key Sim, 1 auditoria/IP/24h sem qualquer registo, JSON completo
Checks de legibilidade para IA / era LLM Não estão no módulo on-page Não aplicável (só SERPs) Módulo dedicado: llms.txt, schema para IA, conteúdo apto para citações, clareza semântica
PDF com marca branca Não disponibilizado Não disponibilizado POST /api/audits/:id/pdf devolve um PDF com o teu logo e cores
Servidor MCP para agentes IA Sem MCP oficial Sem MCP oficial Sim, mesmas chaves Bearer, mesmo motor de auditoria, compatível com Claude Code, Cursor e ChatGPT
Estilo de autenticação HTTP Basic com login + password (raro em stacks modernas) Chave API na query string (?access_key=…) Cabeçalho padrão Authorization: Bearer ms_live_xxx

Preços da API REST

A API REST está incluída no Pro 49 $/mês. As contas Pro recebem 5.000 chamadas de API por mês em qualquer um dos doze endpoints autenticados com token. O endpoint de auditoria anónima é gratuito para todos (limitado a 1 por IP a cada 24 h). As contas Free e Starter podem consultar a documentação e gerar tokens, mas as chamadas autenticadas com token devolvem 403 até passarem a Pro. As mesmas chaves ms_live_ funcionam tanto para esta API REST como para o servidor MCP do MetricSpot, contra a mesma quota mensal partilhada.

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)
  • ·Relatórios comparativos com concorrentes (até 3 concorrentes)
  • ·Domínios em seguimento ilimitados

Ver limites e preços dos planos →

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 as mesmas ferramentas 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/history?url= depois de cada auditoria para entregar um gráfico de evolução da pontuação ao longo do tempo, junto com o último PDF com a tua marca.

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 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 onze endpoints autenticados com token requerem o plano Pro a 49 $/mês, que inclui 5.000 chamadas de API por mês sem custo adicional.

Qual a diferença para o servidor MCP?

O mesmo motor de auditoria, as mesmas 154 regras em 15 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 154 regras em 15 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.

Quais são os limites de uso?

O endpoint anónimo está limitado a 1 auditoria por IP a cada 24 horas. O acesso à API requer Pro 49 $/mês. O Pro inclui 5.000 chamadas de API por mês. Free e Starter não incluem acesso à API. O endpoint anónimo continua gratuito (1 por IP a cada 24 h).

O que acontece se passar das 5.000 chamadas num mês?

O endpoint devolve HTTP 429 com o corpo { error: "quota_exceeded", used: 5000, limit: 5000 }. A quota reinicia-se no início do mês de calendário seguinte. Se precisares de uma quota mais alta, fala connosco pelo formulário de suporte e combinamos um escalão personalizado.

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