Início rápido da API REST

O que a API REST da MetricSpot faz

A API REST da MetricSpot é uma interface JSON sobre HTTPS em app.metricspot.com que envolve o mesmo pipeline de auditoria que alimenta o painel. Expõe seis endpoints: rodar uma auditoria, buscar uma por id, listar auditorias recentes, gerar um PDF com a sua marca, e ler o tráfego orgânico das propriedades Google Analytics 4 e Search Console vinculadas.

Capacidades:

• Rodar uma auditoria anónima one-shot em qualquer URL público (sem auth, 1 por IP a cada 24h).
• Enfileirar uma auditoria completa de forma assíncrona e fazer polling até completar.
• Buscar o envelope de uma auditoria por id com pontuação, divisão por módulo e findings.
• Listar auditorias recentes, deduplicadas por URL.
• Disparar a geração de PDF e fazer stream do ficheiro assim que estiver pronto.
• Ler um snapshot de 28 dias de tráfego orgânico para qualquer auditoria, com cache de 24h.

A API é a mesma superfície com que o painel oficial fala. Tudo o que vê na UI, um cliente API pode reproduzir.

Por que importa

Uma API REST transforma auditorias em bloco de construção. Um bot de CI pode auditar um preview deploy e fazer o build falhar em findings vermelhos. Um fluxo Zapier pode rodar uma auditoria semanal e postar a pontuação no Slack. Uma agência de relatórios pode puxar PDFs para 200 clientes num agendamento. Nenhum desses casos precisa de automação de browser: apenas HTTPS e um token Bearer.

Fluxos concretos:

• Um bot audit-on-PR chama POST /api/audits quando uma URL de preview é lançada, faz polling em GET /api/audits/:id até status === "completed", e posta a diferença de pontuação de volta no PR.
• Um zap semanal chama GET /api/audits para listar cada URL auditada este mês, e dispara uma mensagem Slack se alguma pontuação caiu mais de 5 pontos.
• Um cron de agência white-label busca POST /api/audits/:id/pdf durante a noite para cada domínio de cliente e envia o PDF renderizado por email pela manhã.

Como usar

Todos os endpoints exceto POST /api/public/audit exigem uma chave API Bearer gerada na sua conta MetricSpot. A auditoria anónima é limitada por IP e pula PageSpeed Insights propositadamente para manter o custo previsível.

Cabeçalho de autenticação:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gere uma chave em app.metricspot.com/settings/api-keys. Até 10 chaves ativas por conta. As chaves começam com ms_live_ e são mostradas apenas uma vez na criação.

Endpoints

Método	Caminho	Auth	Limite
POST	/api/public/audit	nenhuma	1 por IP a cada 24h
POST	/api/audits	Bearer	Free 10/mês, Starter 50/mês, Pro ilimitado (mais cooldown por domínio)
GET	/api/audits	Bearer	nenhuma além do plano
GET	/api/audits/:id	Bearer	nenhuma além do plano
POST	/api/audits/:id/pdf depois GET /api/pdfs/:id	Bearer	nenhuma além do plano
GET	/api/audits/:id/google	Bearer + Pro (GA4 / GSC vinculados)	nenhuma, cache 24h

O catálogo legível por máquina está em /.well-known/api-catalog seguindo o RFC 9727.

Início rápido: auditoria anónima (sem chave)

curl -X POST https://app.metricspot.com/api/public/audit \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com"}'

Início rápido: auditoria autenticada + polling

# 1. Enfileirar
curl -X POST https://app.metricspot.com/api/audits \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com"}'

# 2. Polling (substitua 12345 pelo audit_id devolvido)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Início rápido: Node fetch

const res = await fetch("https://app.metricspot.com/api/audits", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
const { audit } = await res.json();
console.log(audit.id, audit.status);

Início rápido: Python httpx

import httpx

r = httpx.post(
    "https://app.metricspot.com/api/audits",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"url": "https://example.com"},
    timeout=30.0,
)
print(r.json()["audit"])

Envelope de resposta

Toda resposta bem-sucedida é JSON. Endpoints mutantes devolvem 201 Created com o recurso criado; endpoints de leitura devolvem 200 OK com o recurso e dados relacionados (findings, plan, cooldown) que o painel usa para renderizar a mesma vista.

Erros são JSON com pelo menos error e código HTTP; alguns endpoints adicionam message para detalhe legível.

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Bearer ausente ou inválido	Gere uma chave em app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Token válido mas sem permissão para este recurso (auditoria de outro)	Use a chave da conta proprietária
RATE_LIMITED (429)	Teto de IP anónimo ou cooldown por domínio	Aguarde a janela indicada
QUOTA_EXCEEDED (402)	Quota mensal do plano esgotada	Upgrade em app.metricspot.com/billing
INVALID_URL (400)	URL não parseável, não absoluta, ou > 2000 caracteres	Passe um URL absoluto https://
AUDIT_NOT_FOUND (404)	audit_id não existe ou não é seu	Liste suas auditorias para obter um id válido
UPSTREAM_FAILED (5xx)	Falha em PageSpeed Insights, GA4 ou GSC	Tente novamente com backoff

Perguntas frequentes

A API REST é gratuita?

O endpoint anónimo (POST /api/public/audit) é gratuito, limitado a 1 auditoria por IP a cada 24h, e pula Core Web Vitals para manter o custo previsível. Os cinco endpoints autenticados contam contra o seu plano: Free 10 auditorias por mês, Starter 50, Pro ilimitado. Listar, obter, PDF e tráfego orgânico não têm custo adicional por chamada.

Onde está a especificação OpenAPI?

O catálogo legível por máquina está em https://metricspot.com/.well-known/api-catalog seguindo o RFC 9727. Ele aponta para a spec JSON de cada endpoint e é o primeiro que os agentes de descoberta leem.

Quanto tempo demora uma auditoria?

10 a 30 segundos em sites típicos. Alvos pesados em JS ou sites com muito structured data podem demorar até 90 segundos. PageSpeed Insights roda em paralelo com o crawler, então o gargalo costuma ser a resposta PSI da Google.

Posso usar a API a partir do browser?

O endpoint anónimo aceita CORS de metricspot.com. Endpoints autenticados não definem CORS permissivo por design: tokens vivem no servidor, nunca no JavaScript do cliente. Use uma função serverless ou rota backend como proxy.