# Reference Census

> Audit a published API reference against its own OpenAPI contract so an integrator never has to guess. Paste the
> spec (JSON or YAML - read in the browser, never sent) and the operations the published reference shows; the page
> builds the census both ways, grades every operation, measures coverage, ranks the remediation tier and the stage the
> team has reached, and writes a Spectral ruleset for the lint gate. Metered runs write the audit report, and the
> remediation plan. Built on the SkillSafe skill @samber/api-reference-quality, from samber/developer-platform-skills
> (MIT), by Samuel Berthe.

https://reference-census.skillsafe.ai/

## What is free
- The census: every operation in the spec against the published reference, both ways - live but undocumented, documented but removed; path parameters matched by position; local $ref pointers resolved, an unresolved one flagged.
- Every operation graded with a severity (blocker, major, minor): a description, every parameter with type, required-ness, description and example, at least one 4xx, every error response with its cause and fix (a bare status name does not count), request and response examples, a snippet per shipped SDK language (relabelled curl is not parity), an idempotency note on state-changing calls.
- Coverage percentages and this page's own completeness score (not a RateMyOpenAPI score).
- The rankings: the remediation tier (lint gate only, lint plus contract tests, generated-docs migration) and the stage reached of five.
- A Spectral ruleset for the completeness gate, and exports: the census (.csv), the checks (.csv), everything (.json).
- Re-check after a fix: the next census of the same API is compared with the last saved one (score, coverage, operations fixed or worse). The published list can be pasted straight from the docs navigation.

## The metered lanes
Two tasks on gpt-terra, metered per run, routed by `task`. Input string fields: `task` (audit or remediate), `team`, `census` (the page's census - never the spec), `carry` (remediate only: the audit's decisions) and `facts`.
- `audit` replies with `summary`, `drift`, `priorities` (operation, severity, finding, fix), `census` (each discrepancy with its direction and action), `benchmark` (Stripe and Twilio), `quadrant` and `caveats`.
- `remediate` replies with `summary`, `tier`, `stages`, `gates`, `ci`, `reaudit`, `trends` and `caveats`.
The page holds every reply to its census: every blocker named at its census severity, every discrepancy covered both ways, no percentage the census does not show, every published figure labelled; the ranked tier, exactly the stages in range, the four gates scoped to the tier.

## Links
- API tutorial: https://reference-census.skillsafe.ai/api.html
- Source skill: https://skillsafe.ai/skill/@samber/api-reference-quality