# One OpenAPI spec, every surface

> How the API contract drives the docs, the endpoint pages and the machine-readable files we publish.

Canonical: https://corpoapi.com/blog/one-spec-everywhere

2026-03-11

## Key takeaways

- One contract: an OpenAPI 3.1 file describes every operation at a single URL.

- The v1 operations ship from one contract: search, company, officers, verify, batch verify, VAT, coverage, usage and health.

- llms.txt, robots.txt and pricing.md are regenerated from the same content on every build.

The API contract is the single source of truth. Everything a developer reads is generated from it or validated against it: the reference docs, the endpoint pages and the machine-readable files.

## The contract

`corpo_openapi.yaml` is an OpenAPI 3.1 document. It defines the request and response shapes for every operation: authentication, pagination, the error schema, and the freshness block that says where a record came from. Build teams code against that file, not against a prose description that drifts from the code.

## The surfaces

From one contract we derive several things:

- The reference docs are generated from the spec, so a schema change appears in the docs the moment it lands.
- The endpoint pages under `/endpoints` describe the same operations, with the price taken from `content/pricing.yaml`.
- `llms.txt`, `robots.txt` and `pricing.md` are written on every build from the same site data, so an LLM or a crawler reads the same facts a human does.

## Why generate instead of hand-write

A hand-maintained pricing table is a table that goes stale. A hand-written error list is a list that drifts from the codes the server actually returns. Generating the machine-facing surfaces from one source removes that class of bug: the endpoint page, the JSON-LD, the `pricing.md` line and the API itself cannot disagree.

The tradeoff is that the source has to be real. If the spec is wrong, every surface is wrong in the same way, which is at least a single place to fix.