Démarrage rapide de l'API REST

Ce que fait l’API REST de MetricSpot

L’API REST de MetricSpot est une interface JSON sur HTTPS à app.metricspot.com qui enveloppe le même pipeline d’audit que celui qui anime le tableau de bord. Elle expose six endpoints : lancer un audit, en récupérer un par id, lister les audits récents, générer un PDF avec votre marque, et lire le trafic organique depuis Google Analytics 4 et Search Console liés.

Capacités :

• Lancer un audit anonyme one-shot sur toute URL publique (sans auth, 1 par IP toutes les 24h).
• Mettre en file un audit complet de manière asynchrone et poller jusqu’à la fin.
• Récupérer l’enveloppe d’un audit par id avec score, ventilation par module et findings.
• Lister les audits récents, dédupliqués par URL.
• Déclencher la génération PDF et streamer le fichier dès qu’il est prêt.
• Lire un snapshot 28 jours de trafic organique pour tout audit, mis en cache 24h.

L’API est la même surface avec laquelle parle le tableau de bord officiel. Tout ce qui est visible dans l’UI, un client API peut le reproduire.

Pourquoi c’est important

Une API REST transforme les audits en brique de construction. Un bot CI peut auditer un preview-deploy et faire échouer le build sur des findings rouges. Un flux Zapier peut lancer un audit hebdomadaire et poster le score dans Slack. Une agence de reporting peut tirer des PDF pour 200 clients selon un planning. Aucun de ces cas ne nécessite d’automation navigateur : juste HTTPS et un token Bearer.

Workflows concrets :

• Un bot audit-sur-PR appelle POST /api/audits quand une preview URL est déployée, poll GET /api/audits/:id jusqu’à status === "completed" et reposte le delta de score sur le PR.
• Un zap hebdomadaire appelle GET /api/audits pour lister chaque URL auditée ce mois-ci, puis déclenche un message Slack si un score baisse de plus de 5 points.
• Un cron d’agence white-label tire POST /api/audits/:id/pdf la nuit pour chaque domaine client et envoie le PDF rendu par email le matin.

Comment l’utiliser

Tous les endpoints sauf POST /api/public/audit nécessitent une clé API Bearer générée depuis votre compte MetricSpot. L’audit anonyme est plafonné par IP et omet volontairement PageSpeed Insights pour garder le coût prévisible.

En-tête d’authentification :

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Créez une clé sur app.metricspot.com/settings/api-keys. Jusqu’à 10 clés actives par compte. Les clés commencent par ms_live_ et ne s’affichent qu’une seule fois à la création.

Endpoints

Méthode	Chemin	Auth	Limite
POST	/api/public/audit	aucune	1 par IP toutes les 24h
POST	/api/audits	Bearer	Free 10/mois, Starter 50/mois, Pro illimité (plus cooldown par domaine)
GET	/api/audits	Bearer	aucune au-delà du plan
GET	/api/audits/:id	Bearer	aucune au-delà du plan
POST	/api/audits/:id/pdf puis GET /api/pdfs/:id	Bearer	aucune au-delà du plan
GET	/api/audits/:id/google	Bearer + Pro (GA4 / GSC liés)	aucune, cache 24h

Le catalogue lisible par machine est à /.well-known/api-catalog selon RFC 9727.

Démarrage rapide : audit anonyme (sans clé)

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

Démarrage rapide : audit authentifié + polling

# 1. Mettre en file
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. Poller (remplacez 12345 par l'audit_id renvoyé)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Démarrage rapide : 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);

Démarrage rapide : 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"])

Enveloppe de réponse

Toute réponse réussie est en JSON. Les endpoints mutants renvoient 201 Created avec la ressource créée ; les endpoints de lecture renvoient 200 OK avec la ressource et les données liées (findings, plan, cooldown) que le tableau de bord utilise pour afficher la même vue.

Les erreurs sont en JSON avec au minimum error et un code HTTP ; certains endpoints ajoutent message pour un détail lisible.

Erreurs courantes

Code	Quand	Action
UNAUTHORIZED (401)	Bearer manquant ou invalide	Créez une clé sur app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Token valide mais sans permission pour cette ressource (audit d’un autre)	Utilisez la clé du compte propriétaire
RATE_LIMITED (429)	Plafond IP anonyme ou cooldown par domaine	Attendez la fenêtre indiquée
QUOTA_EXCEEDED (402)	Quota mensuel épuisé	Upgrade sur app.metricspot.com/billing
INVALID_URL (400)	URL non parsable, non absolue ou > 2000 caractères	Passez une URL absolue https://
AUDIT_NOT_FOUND (404)	audit_id inexistant ou ne vous appartient pas	Listez vos audits pour obtenir un id valide
UPSTREAM_FAILED (5xx)	Panne PageSpeed Insights, GA4 ou GSC	Réessayez avec backoff

Questions fréquentes

L’API REST est-elle gratuite ?

L’endpoint anonyme (POST /api/public/audit) est gratuit, plafonné à 1 audit par IP toutes les 24h, et omet Core Web Vitals pour garder le coût prévisible. Les cinq endpoints authentifiés comptent contre votre plan : Free 10 audits par mois, Starter 50, Pro illimité. Lister, obtenir, PDF et trafic organique n’ont pas de coût supplémentaire par appel.

Où est la spec OpenAPI ?

Le catalogue lisible par machine est à https://metricspot.com/.well-known/api-catalog selon RFC 9727. Il lie la spec JSON de chaque endpoint et c’est ce que lisent en premier les agents de découverte.

Combien de temps prend un audit ?

10 à 30 secondes sur les sites typiques. Les cibles riches en JS ou les sites avec beaucoup de structured data peuvent prendre jusqu’à 90 secondes. PageSpeed Insights tourne en parallèle du crawler, donc le goulot d’étranglement est généralement la réponse PSI de Google.

Puis-je utiliser l’API depuis le navigateur ?

L’endpoint anonyme accepte CORS depuis metricspot.com. Les endpoints authentifiés ne définissent pas de CORS permissif par conception : les tokens vivent côté serveur, jamais dans le JavaScript client. Utilisez une fonction serverless ou une route backend comme proxy.