RFC 9727 is the Standards Track specification that defines the /.well-known/api-catalog URI and the api-catalog link relation. A request to that path returns a Linkset document listing the publisher’s APIs, each one an anchor with links to its machine-readable description (service-desc), its documentation (service-doc), further metadata (service-meta) and its health (status).
API Catalog
API Catalog gives a publisher one fixed place to say which APIs it has. Kevin Smith of Vodafone
published it as Standards Track in June 2025. It defines two things: the /.well-known/api-catalog
URI and an api-catalog link relation, so a page or an HTTP Link header can point at a catalog that
lives somewhere else.
/.well-known/api-catalog- The registered path. It MUST support the Linkset format,application/linkset+json(RFC 9264), and SHOULD signal the profilehttps://www.rfc-editor.org/info/rfc9727.linkset/anchor- One entry per API, anchored at the API’s own URI.item- Links from the catalog to each API it lists.service-desc- The machine-readable description. The RFC gives an OpenAPI document as the example.service-doc,service-meta,status- Human documentation, further metadata, and the API’s health endpoint, all link relations from RFC 8631.
A publisher that already describes its APIs in another format may keep it, but it MUST also publish a Linkset with at least the links to each API. So the catalog sits alongside formats like APIs.json rather than replacing them.
It is in the same family as /.well-known/oauth-protected-resource
(RFC 9728), /.well-known/agent-card.json and
/.well-known/ai-catalog.json: a document at a fixed path that a client, or an agent, can read
without being told where to look. Soft 200s affect it just as they do the others. Credit
only a response that parses as a Linkset, not a status code.
