{
 "acronym": "RFC 9727",
 "adoption": {
  "by": null,
  "level": "unmeasured",
  "probe_run": null
 },
 "aliases": [
  "api-catalog"
 ],
 "analog": "sitemap.xml, but for APIs instead of pages",
 "collisions": [
  "Not to be confused with the ARD ecosystem's ai-catalog.json well-known file (see ard), a different, agent-specific well-known artifact with no normative relationship to this RFC"
 ],
 "discovery": {
  "mechanism": "well-known URI plus an 'api-catalog' HTTP Link header / HTML link relation",
  "path": "/.well-known/api-catalog"
 },
 "dispute": null,
 "evidence": [
  {
   "claim": "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.",
   "date": "2025-06",
   "label": "VERIFIED",
   "url": "https://www.rfc-editor.org/rfc/rfc9727.html"
  },
  {
   "claim": "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.",
   "date": "2026-09-06",
   "label": "VERIFIED",
   "url": "https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml"
  }
 ],
 "form": "well-known-file",
 "governance": "IETF; published as a Standards Track RFC with the IETF as change controller",
 "group": null,
 "history": [
  {
   "date": "2026-09-06",
   "note": "new record created from the occupant-diff candidate list; verified against RFC 9727 text via rfc-editor.org"
  },
  {
   "date": "2026-09-06",
   "note": "fix round 1: added second evidence entry (IANA Well-Known URIs registry, fetched directly) confirming permanent registration"
  }
 ],
 "id": "api-catalog-rfc9727",
 "implementation": "unknown",
 "last_verified": "2026-09-06",
 "name": "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs",
 "native_status": "Proposed Standard (errata exist)",
 "origin": {
  "date": "2025-06",
  "org": "Vodafone (Kevin Smith)"
 },
 "part_of": null,
 "parties": [
  "agent-site"
 ],
 "phase": "stable",
 "probe": {
  "method": "GET",
  "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",
  "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",
  "path": "https://{origin}/.well-known/api-catalog"
 },
 "question": "Given a publisher's domain, where is the machine-readable list of the APIs it exposes?",
 "scope": "general",
 "spec_url": "https://www.rfc-editor.org/rfc/rfc9727.html",
 "step": "discover",
 "summary_md": "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.\n\nIt 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].\n\nIt 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].\n\nCurrent 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.\n\nWhat 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.",
 "track": "ietf",
 "version": {
  "date": "2025-06",
  "label": "RFC 9727"
 },
 "url": "https://agenticweb.wiki/protocols/api-catalog-rfc9727/",
 "category": "discover",
 "type": "protocol"
}