# 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é :

```bash
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.