# API concepts

> Team, project, campaign, crawl, reports and modules, and how the API links them.

The API follows the product model. Understanding it avoids most integration mistakes.

## Team

The team is the billed entity: the plan, the quotas and the API rate limits belong to it. A token acts for one team only, and everything it sees belongs to that team. A resource of another team answers `404`, never `403`: the API does not confirm it exists.

## Project

A project is a site followed over time, identified by a UUID (`id`). It holds its campaigns, its crawls, its modules and its health scorecard:

```bash
curl "https://api.nessflow.com/v1/projects/$PROJECT_ID/scorecard" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

The scorecard returns five separate pillars, with no global average: pillars of different natures do not add up. A pillar that cannot be measured has `score: null`, never `0`.

## Campaign

A campaign is a reusable crawl configuration: start URL, page budget, JavaScript rendering, options (PageSpeed, accessibility…) and schedule. A project has at least one, created with it.

## Crawl

A crawl is a run of a campaign. Two crawls of the same campaign compare, unless one is **truncated** (`truncated: true`, stopped at its deadline): it then describes an arbitrary part of the site, and is never used as a baseline.

## Reports and modules

Each crawl produces frozen reports (issues, pages, PageSpeed, GEO, accessibility, trust foundation, internal linking). The modules outside the health score (rankings, Search Console, backlinks, security, logs) are read per project and carry a trend, never a grade.

## Three states, never two

Everywhere, the API tells apart **measured**, **measured negative** (a fact: "out of the top 100") and **not measured** (`null`, or a `status` such as `pending` or `unavailable`). Never read `null` as zero.