What this check tests
The audit requests /.well-known/api-catalog with Accept: application/linkset+json. The crawl accepts the response only if the status is 200, the media type is exactly application/linkset+json (parameters such as profile are ignored), and the body differs from what your server returns for a random path under /.well-known/, so a catch-all page is not mistaken for a catalog.
Then run() reads the body:
- Fail 0: nothing accepted; or the body is not a JSON object with a
linksetarray; or no entry in the array qualifies. - Pass 100: at least one entry qualifies. The message gives the count.
- Skip: replaces a fail when the public API check failed or was skipped. A pass is kept regardless.
An entry qualifies when it is an object with a string anchor and at least one of item, service-desc or service-doc as a non-empty array in which every element is an object with a string href.
The check does not test everything RFC 9727 asks for. It does not look at the profile parameter, the HEAD request that should return Link headers, or whether the href targets resolve.
Why it matters to agents
RFC 9727 (June 2025, Standards Track) gives publishers one well-known address from which a client can learn what APIs they offer, without searching the site. The catalog must be in Linkset format (application/linkset+json, RFC 9264) and must include hyperlinks to the API endpoints. It suggests adding metadata such as usage policies, version information and links to OpenAPI definitions. The service-desc relation points to a machine-readable description of an API and service-doc to human-readable documentation.
For an agent this replaces guessing paths like /api/ or /openapi.json. The standard is new, and the RFC says nothing about how many clients read it. Treat it as a low-cost way to make the API you already have easy to find, not as a known lever for traffic.
If you have no public API, there is nothing to list, and the check is skipped.
How to fix it
Only if you publish an API. Serve this at https://example.com/.well-known/api-catalog with Content-Type: application/linkset+json:
{
"linkset": [
{
"anchor": "https://example.com/api/v1",
"service-desc": [
{ "href": "https://example.com/openapi.json", "type": "application/json" }
],
"service-doc": [
{ "href": "https://example.com/developers", "type": "text/html" }
]
}
]
}
- One entry per API.
anchoris the API's address; the links point to its description and documentation. This shape follows RFC 9727 appendix A.1. - RFC 9727 recommends a
profileparameter on the content type,profile="https://www.rfc-editor.org/info/rfc9727", and a response to HEAD requests with aLinkheader. The audit does not require either, but add them when you can. - Serve the file from a static path. Do not let a catch-all route answer
/.well-known/api-catalogwith an HTML page. - Point
service-descat an OpenAPI document andservice-docat your developer portal. - If your APIs run on several domains, RFC 9727 section 5.1 recommends publishing the catalog on each, with the others redirecting to one canonical copy.
Check with curl -si -H 'Accept: application/linkset+json' https://example.com/.well-known/api-catalog and confirm the status and Content-Type.