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

[1 · Discover](/category/discover/)

| api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs |
| --- |
| Category | [Discover](/category/discover/) |
| Governed by | IETF; published as a Standards Track RFC with the IETF as change controller |
| Status | Proposed Standard (errata exist) |
| Phase | stable |
| Implementation | unknown |
| Adoption | unmeasured |
| Version | RFC 9727 (2025-06) |
| Specification | [https://www.rfc-editor.org/rfc/rfc9727.html](https://www.rfc-editor.org/rfc/rfc9727.html) |
| Found at | /.well-known/api-catalog |
| Acronym 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 |
| Last checked | 2026-09-06 |

[Discover](/category/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]](#ref-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]](#ref-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]](#ref-1). A GET request must return the catalog document; a HEAD request must return a Link header carrying the relation [[1]](#ref-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]](#ref-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]](#ref-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]](#ref-1). Security guidance is largely operational: use TLS, avoid leaking internal/private APIs into a public catalog, and rate-limit the endpoint [[1]](#ref-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]](#ref-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  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](/mcp/server-card): 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
- 2026-09-06 — new record created from the occupant-diff candidate list; verified against RFC 9727 text via rfc-editor.org
- 2026-09-06 — fix round 1: added second evidence entry (IANA Well-Known URIs registry, fetched directly) confirming permanent registration

## Instances

- [agenticweb.wiki](https://agenticweb.wiki/.well-known/api-catalog) · Observed 2026-09-06 · site
- [Dries Buytaert (dri.es) api-catalog](https://dri.es/helping-agents-discover-my-site-search-with-an-api-catalog) · Observed 2026-07-22 · site
- [Cloudflare (docs)](https://github.com/cloudflare/cloudflare-docs/commit/4732607805c4fab35530c9466f62e54a29f20e48) · Observed 2026-04-22 · service
- [Supabase](https://github.com/supabase/supabase/pull/44880) · Observed 2026-04-15 · business

Every instance with its source is listed on the [instances page](/instances/).

## See also

- Not to be confused with: 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

## References

- 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](https://www.rfc-editor.org/rfc/rfc9727.html) (2025-06) VERIFIED
- 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](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml) (2026-09-06) VERIFIED

[JSON](/data/protocols/api-catalog-rfc9727.json) · [Markdown](/protocols/api-catalog-rfc9727/index.md)