An API description is useful only after a client finds it. RFC 9727 addresses that first step with a stable address for an API catalog (Smith, secs. 1.1-2). Its contribution is modest and specific: a publisher can place typed links to public API resources behind a route that a supporting client already knows how to request (Smith, secs. 3-4.1). The catalog does not prove that an API works, that its description is accurate, or that any particular client will use it.
For a site owner, an API catalog is an index, not an integration.
The route is predictable; the API is not
RFC 8615 reserves the /.well-known/ path prefix so individual specifications can register stable locations for metadata. It does not define a generic resource at /.well-known/, and it leaves the relevant hostname and the scope of discovered metadata to the application-specific specification (Nottingham, secs. 1, 3).
RFC 9727 supplies those missing details for API catalogs. A conforming publisher resolves an HTTPS GET request to /.well-known/api-catalog to an API catalog document. It also resolves an HTTPS HEAD request at that route with a Link header carrying the relations defined by the RFC (Smith, sec. 2). The underlying catalog may live elsewhere; the well-known route is the stable reference to it.
The label "well-known" is easy to overread. It means the location has a registered convention, not that every crawler, agent, SDK, or search engine requests it. A client still has to implement the convention, choose the correct origin, retrieve the response, and decide what to do with the links.
Read the catalog as a set of typed links
RFC 9727 requires the catalog to include links to API endpoints. It recommends adding useful metadata such as usage policies, API versions, and links to OpenAPI descriptions, either in the catalog or at the listed endpoint resources (Smith, sec. 4.1). The required representation is a JSON Linkset served as application/linkset+json; other negotiated formats are optional additions, not substitutes for that representation (Smith, secs. 4.2, 6.2).
In the JSON Linkset model, a top-level linkset array contains link-context objects. Each relation name maps to an array of link-target objects, and each target has an href (Wilde and Van de Sompel, secs. 4.2.1-4.2.3). Combining two patterns from RFC 9727, a compact catalog can link the catalog to an API endpoint, then link that endpoint to its machine-readable description and human documentation (Smith, apps. A.1-A.2):
{
"linkset": [
{
"anchor": "https://example.com/.well-known/api-catalog",
"item": [{ "href": "https://api.example.com/v1" }]
},
{
"anchor": "https://api.example.com/v1",
"service-desc": [{ "href": "https://api.example.com/openapi.json" }],
"service-doc": [{ "href": "https://example.com/docs/api" }]
}
]
}
The relation names make those roles explicit. A client does not have to guess whether one URL is an endpoint, a contract, or a guide from its filename. Even so, the linked resources remain separate statements by the publisher. A stale service-desc link is still stale, and a listed endpoint is not evidence that an unauthenticated caller may use it.
Publication is a maintenance task
A catalog should change with the API portfolio. RFC 9727 recommends removing stale entries as part of the release lifecycle, checking syntax and metadata, and reviewing a public catalog so it does not expose private APIs or sensitive information (Smith, secs. 5.4, 8). Those are maintenance practices, not discoverability tricks.
For a small API, the practical work is equally small: serve the required Linkset representation, expose the well-known route over HTTPS, include only intentionally public endpoints, link to current descriptions and policies, test GET and HEAD behavior, and keep the catalog in the same release process as the API documentation.
What this check can and cannot establish
When API or protocol checks are in scope, MachineRead requests /.well-known/api-catalog, /.well-known/api-catalog.json, and /api-catalog.json. It records an API catalog candidate when a successful response contains at least 20 characters after trimming whitespace and parses as a JSON object or array. Separately, it records a general discovery signal when the audited target page's HTTP Link header contains one of several configured tokens, including api-catalog. These are deliberately narrow discovery signals.
The check does not perform a complete RFC 9727 conformance test. It does not establish that the server implements the required HEAD response, sends the required Linkset media type, uses every relation correctly, or keeps each target current. It also does not test API authentication, authorization, rate limits, runtime responses, security, or client support for the catalog. A missing result means the audit did not observe this public signal under its request conditions, not that the publisher has no API.
Works Cited
Nottingham, Mark. "Well-Known Uniform Resource Identifiers (URIs)." RFC 8615, Internet Engineering Task Force, May 2019, RFC Editor, https://www.rfc-editor.org/rfc/rfc8615.html. Accessed 7 Aug. 2026.
Smith, Kevin. "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs." RFC 9727, Internet Engineering Task Force, June 2025, RFC Editor, https://www.rfc-editor.org/rfc/rfc9727.html. Accessed 7 Aug. 2026.
Wilde, Erik, and Herbert Van de Sompel. "Linkset: Media Types and a Link Relation Type for Link Sets." RFC 9264, Internet Engineering Task Force, July 2022, RFC Editor, https://www.rfc-editor.org/rfc/rfc9264.html. Accessed 7 Aug. 2026.
See also
- Methodology reference - documents the api-catalog probe and the machine_surfaces check group
- Launch post - explains the audit's evidence boundaries
- Related: openapi.json and ai-catalog.json