REST-API-Schnellstart

Was MetricSpots REST-API macht

MetricSpots REST-API ist eine JSON-über-HTTPS-Schnittstelle auf app.metricspot.com, die dieselbe Audit-Pipeline kapselt, die das Dashboard antreibt. Sie stellt sechs Endpunkte bereit: Audit starten, per id abrufen, jüngste Audits auflisten, ein gebrandetes PDF erzeugen und den organischen Traffic aus verknüpftem Google Analytics 4 und Search Console lesen.

Funktionen:

• One-shot anonymen Audit auf jede öffentliche URL starten (keine Auth, 1 pro IP pro 24h).
• Vollständigen Audit asynchron einreihen und bis zur Fertigstellung pollen.
• Audit-Envelope per id holen mit Score, Modulaufschlüsselung und Findings.
• Jüngste Audits auflisten, dedupliziert nach URL.
• PDF-Generierung anstoßen und Datei streamen, sobald fertig.
• 28-Tage-Snapshot des organischen Traffics für jeden Audit lesen, 24h gecached.

Die API ist dieselbe Oberfläche, mit der das Dashboard spricht. Alles, was du in der UI siehst, kann ein API-Client reproduzieren.

Warum das wichtig ist

Eine REST-API macht aus Audits einen Baustein. Ein CI-Bot kann ein Preview-Deploy auditieren und den Build bei roten Findings brechen. Ein Zapier-Flow kann wöchentlich auditieren und den Score in Slack posten. Eine Reporting-Agentur kann PDFs für 200 Kunden nach Zeitplan ziehen. Keines davon braucht Browser-Automation: nur HTTPS und ein Bearer-Token.

Konkrete Workflows:

• Ein Audit-on-PR-Bot ruft POST /api/audits auf, wenn eine Preview-URL deployed wird, pollt GET /api/audits/:id bis status === "completed" und postet den Score-Delta zurück in den PR.
• Ein wöchentlicher Zapier-Zap ruft GET /api/audits auf, um jede in diesem Monat auditierte URL zu listen, und triggert eine Slack-Nachricht, wenn ein Score um mehr als 5 Punkte gefallen ist.
• Ein White-Label-Agentur-Cron holt POST /api/audits/:id/pdf über Nacht für jede Kunden-Domain und mailt das PDF am Morgen.

Wie du sie nutzt

Alle Endpunkte außer POST /api/public/audit brauchen einen Bearer-API-Key aus deinem MetricSpot-Konto. Der anonyme Audit ist per IP gedeckelt und überspringt absichtlich PageSpeed Insights, um die Kosten kalkulierbar zu halten.

Auth-Header:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel erzeugen auf app.metricspot.com/settings/api-keys. Bis zu 10 aktive Schlüssel pro Konto. Schlüssel beginnen mit ms_live_ und werden nur einmal bei Erstellung angezeigt.

Endpunkte

Methode	Pfad	Auth	Rate Limit
POST	/api/public/audit	keine	1 pro IP pro 24h
POST	/api/audits	Bearer	Free 10/Monat, Starter 50/Monat, Pro unbegrenzt (plus Domain-Cooldown)
GET	/api/audits	Bearer	keiner über den Plan hinaus
GET	/api/audits/:id	Bearer	keiner über den Plan hinaus
POST	/api/audits/:id/pdf dann GET /api/pdfs/:id	Bearer	keiner über den Plan hinaus
GET	/api/audits/:id/google	Bearer + Pro (GA4 / GSC verknüpft)	keiner, 24h gecached

Der maschinenlesbare Katalog liegt unter /.well-known/api-catalog gemäß RFC 9727.

Schnellstart: anonymer Audit (ohne Key)

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

Schnellstart: authentifizierter Audit + Polling

# 1. Einreihen
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. Pollen (ersetze 12345 durch die zurückgegebene audit_id)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Schnellstart: 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);

Schnellstart: 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"])

Antwort-Envelope

Jede erfolgreiche Antwort ist JSON. Mutierende Endpunkte liefern 201 Created mit der neu erstellten Ressource; Read-Endpunkte liefern 200 OK mit der Ressource und allen verwandten Daten (Findings, Plan, Cooldown), die das Dashboard zur Anzeige nutzt.

Fehler sind JSON mit mindestens error und einem HTTP-Statuscode; manche Endpunkte ergänzen message für lesbare Details.

Häufige Fehler

Code	Wann	Aktion
UNAUTHORIZED (401)	Bearer-Token fehlt oder ist ungültig	Schlüssel erzeugen auf app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Token gültig, aber nicht für diese Ressource erlaubt (z. B. fremder Audit)	Schlüssel des besitzenden Kontos verwenden
RATE_LIMITED (429)	Anonymer IP-Deckel oder Domain-Cooldown	Angegebenes Fenster abwarten
QUOTA_EXCEEDED (402)	Monatliches Plan-Kontingent verbraucht	Upgraden auf app.metricspot.com/billing
INVALID_URL (400)	URL nicht parsbar, nicht absolut oder länger als 2000 Zeichen	Absolute https://-URL übergeben
AUDIT_NOT_FOUND (404)	audit_id existiert nicht oder gehört dir nicht	GET /api/audits listen und gültige id nehmen
UPSTREAM_FAILED (5xx)	PageSpeed Insights-, GA4- oder GSC-Aussetzer	Mit Backoff erneut versuchen

Häufig gestellte Fragen

Ist die REST-API kostenlos?

Der anonyme Endpunkt (POST /api/public/audit) ist kostenlos, gedeckelt auf 1 Audit pro IP pro 24h und überspringt Core Web Vitals, um die Kosten kalkulierbar zu halten. Die fünf authentifizierten Endpunkte zählen gegen deinen Plan: Free 10 Audits pro Monat, Starter 50, Pro unbegrenzt. List-, Get-, PDF- und Organic-Traffic-Endpunkte verursachen über das referenzierte Audit hinaus keine Kosten pro Aufruf.

Wo ist die OpenAPI-Spec?

Der maschinenlesbare Katalog liegt unter https://metricspot.com/.well-known/api-catalog nach RFC 9727. Er verweist auf die JSON-Spezifikation jedes Endpunkts und ist das, was Discovery-Agenten zuerst lesen.

Wie lange dauert ein Audit?

10 bis 30 Sekunden bei typischen Seiten. JS-lastige Ziele oder Seiten mit viel Structured Data können bis zu 90 Sekunden brauchen. PageSpeed Insights läuft parallel zum Crawler, der Flaschenhals ist meist Googles PSI-Antwortzeit.

Kann ich die API aus dem Browser nutzen?

Der anonyme Endpunkt akzeptiert CORS von metricspot.com. Authentifizierte Endpunkte setzen absichtlich kein permissives CORS: Tokens gehören auf den Server, nie in Client-JavaScript. Nutze eine Serverless-Funktion oder Backend-Route als Proxy.