agenticweb.wiki

api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs RFC 9727

Discover RFC 9727 defines the "api-catalog" well-known URI and a matching "api-catalog" link relation, intended to facilitate automated discovery of a Publisher's APIs [1]. It is a Standards Track IETF RFC, published June 2025, with the IETF itself as change controller and a single named author, Kevin Smith of Vodafone [1]. It predates the current wave of agent-discovery specifications (ARD, DNS-AID, AID, ADP, ARDP, ADS) by roughly a year, and is not agent-specific: it is a general web-API discovery mechanism that this map's occupant-diff process flagged as relevant because it addresses the same "where are this domain's machine-callable capabilities" question the agentic-web specs are now re-solving with different formats.

Overview

It solves API discovery for a domain's own APIs: a publisher hosts a document at /.well-known/api-catalog (or elsewhere, pointed to by the link relation) listing hyperlinks to its API endpoints, in the mandatory Linkset format (application/linkset+json, itself defined by RFC 9264) [1]. A GET request must return the catalog document; a HEAD request must return a Link header carrying the relation [1]. The catalog can nest -- one api-catalog document can point to others via further api-catalog-relation links -- which the RFC recommends for publishers with APIs spread across multiple domains or too many APIs for one flat list [1]. Publishers already using a different catalog format (APIs.json, RESTdesc, HAL, or a schema.org WebAPI extension) may keep it and additionally expose a minimal Linkset-format catalog to satisfy this RFC, using content negotiation to serve either [1].

It does not mandate any particular path for the API endpoints themselves, does not require the catalog to be hosted on the same domain it describes (a publisher can point to a third party's catalog for APIs it does not control), and does not define authentication, versioning policy, or any agent-specific semantics -- it is a pure discovery/link-relation mechanism aimed at human developers and their tooling, not agents specifically [1]. Security guidance is largely operational: use TLS, avoid leaking internal/private APIs into a public catalog, and rate-limit the endpoint [1].

Current state: RFC 9727 is a published Proposed Standard with known errata on file at the RFC Errata system, and carries no revision history beyond the original June 2025 text and its errata [1]. No independent adoption count was located during this verification pass -- the RFC's own text does not claim any deployments, and no third-party survey was found in the sources read.

What is disputed or unknown: whether this general-purpose, agent-agnostic mechanism will be adopted, ignored, or superseded by the newer agent-specific well-known conventions (ARD's ard.json, ADP's agent.json) that solve an overlapping but not identical problem -- API discovery generically versus agentic-resource discovery specifically -- and whether any publisher serves both /.well-known/api-catalog and one of the newer agent-specific manifests at the same origin.

Discovery and probe

well-known URI plus an 'api-catalog' HTTP Link header / HTML link relation · /.well-known/api-catalog

GET https://{origin}/.well-known/api-catalog
parse:     200 response with Content-Type application/linkset+json, body containing a top-level "linkset" array whose entries carry "item" (or other) link relations to API endpoints; a HEAD request instead returns a Link header with rel=api-catalog
on absent: Publisher does not expose an RFC 9727 API catalog at the well-known location; check for an 'api-catalog' Link header or <link rel="api-catalog"> on the site's root response instead, since the RFC allows the catalog to live at any URI the publisher chooses

Live check run by the MCP probe: GET /.well-known/api-catalog. RFC 9727 requires application/linkset+json with a linkset array.

{
 "path": "/.well-known/api-catalog",
 "expect": {
  "content_type": "linkset",
  "json_keys": [
   "linkset"
  ]
 },
 "note": "RFC 9727 requires application/linkset+json with a linkset array."
}

History

Instances

Every instance with its source is listed on the instances page.

See also

References

  1. RFC 9727 (June 2025, Standards Track, sole author Kevin Smith/Vodafone) defines the api-catalog well-known URI and link relation; a publisher MUST resolve GET /.well-known/api-catalog to an API catalog document in the Linkset format (application/linkset+json per RFC 9264), and MAY additionally offer other formats via content negotiation or a different hosting location signposted by the api-catalog link relation. — https://www.rfc-editor.org/rfc/rfc9727.html (2025-06) VERIFIED
  2. IANA's Well-Known URIs registry (fetched 2026-09-06) lists "api-catalog" as a permanent registration, reference RFC9727, change controller IETF, registered 2024-12-23 -- independent confirmation that this well-known path is formally registered and not merely proposed in the RFC text. — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml (2026-09-06) VERIFIED

JSON · Markdown