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:
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.