Rubric / Discoverability

API catalog / OpenAPI

discoverability.api_catalog

weight 1deterministicemerging

An API catalog is published at `/.well-known/api-catalog` (RFC 9727) or an OpenAPI document is reachable at `/openapi.json` or `/openapi.yaml`.

Adoption of what this check tests is still climbing, so failing it is an opportunity rather than a defect. Remediation lists rank these after established fixes, and the weight moves only when measurement earns it.

Definition

Check ID

discoverability.api_catalog

Category

Discoverability

Weight

Counts toward the score

Yes.

Evaluated by

A fixed rule with no threshold of our choosing. The same input always produces the same verdict.

Standard maturity

emerging

Canonical spec

https://datatracker.ietf.org/doc/html/rfc9727

Introduced in

r2026.04.2

Retired in

Still active.

History

Every change to the instrument— including the versions that changed this check

Machine-readable

/rubric.json— this check, and every other, as data

How often this check is right

No rate published. Too few labelled cases to publish a rate: 2 flagged cases (30 needed to publish), 2 defective cases (30 needed to publish). The counts are the honest answer here. The matrix behind discoverability.api_catalog is 4 labelled cases — reported here rather than turned into a percentage that would read as more certain than the evidence is.

Corpus v1, measured under rubric r2026.11.0. Full method and every other check at /rubric/accuracy.

How to fix it

Publish either an `/.well-known/api-catalog` (RFC 9727) referencing your OpenAPI documents, or expose `/openapi.json` directly. Agents that integrate with APIs use these to plan calls.

Does your site pass this check?

Free scan, 30 seconds, no signup — this check and the other 35, with the exact evidence for each verdict.

Scan my site →