Les concepts de l’API
Équipe, projet, campagne, crawl, rapports et modules, et comment l’API les relie.
L’API suit le modèle du produit. Le comprendre évite la plupart des erreurs d’intégration.
Équipe
L’équipe est l’entité facturée : l’offre, les quotas et le débit de l’API lui appartiennent. Un jeton agit pour une seule équipe, et tout ce qu’il voit en fait partie. Une ressource d’une autre équipe répond 404, jamais 403 : l’API ne confirme pas son existence.
Projet
Un projet est un site suivi dans le temps, identifié par un UUID (id). Il porte ses campagnes, ses crawls, ses modules et son bilan de santé :
curl "https://api.nessflow.com/v1/projects/$PROJECT_ID/scorecard" \
-H "Authorization: Bearer $NESSFLOW_TOKEN"Le bilan rend cinq piliers séparés, sans moyenne globale : des piliers de natures différentes ne s’additionnent pas. Un pilier non mesurable a score: null, jamais 0.
Campagne
Une campagne est une configuration de crawl réutilisable : URL de départ, budget de pages, rendu JavaScript, options (PageSpeed, accessibilité…) et planification. Un projet en a au moins une, créée avec lui.
Crawl
Un crawl est une exécution d’une campagne. Deux crawls de la même campagne se comparent, sauf si l’un est tronqué (truncated: true, arrêté à son échéance) : il décrit alors une partie arbitraire du site, et n’est jamais pris comme référence.
Rapports et modules
Chaque crawl produit des rapports figés (anomalies, pages, PageSpeed, GEO, accessibilité, socle de confiance, maillage). Les modules hors score de santé (positions, Search Console, backlinks, sécurité, journaux) se lisent par projet et portent une tendance, jamais une note.
Trois états, jamais deux
Partout, l’API distingue mesuré, mesuré négatif (un fait : « hors du top 100 ») et non mesuré (null, ou un status comme pending ou unavailable). Ne lisez jamais null comme zéro.