AgentGrade

RFC 9727 — api-catalog

Discovery · IETF · IANA registry · Updated 2026-07-31

Status: Proposed Standard (IETF httpapi WG), published June 2025 · Authoritative source

One fixed URL that lists every API a site offers, in a machine-readable linkset — the newest IANA-registered member of the discovery layer, with adoption you can still count on one hand.

RFC 9727 (June 2025) defines /.well-known/api-catalog: a linkset (RFC 9264, served as application/linkset+json) in which each item entry is one of the publisher’s APIs. Entries should carry more than a bare URL — the service-desc relation points at a machine-readable description (in practice, an OpenAPI document), service-doc at human documentation, status at a health endpoint. Unlike most of the agent-discovery layer, this name is actually in the IANA well-known registry (registered December 2024) — see RFC 8615 for how rare that is.

Adoption is thin, and measurably so: a May 2026 probe of 74 major API providers found exactly four serving a real catalog — Cloudflare, Merge.dev, Zuplo, and Memesio (whose catalog lists an MCP server among its APIs). The interesting motion is in tooling: Fern serves an RFC 9727 catalog on its hosted docs sites by default, pitching it as letting “AI agents, MCP clients, and API catalog crawlers discover your APIs without scraping HTML.”

For agents the pitch is the same as the rest of the well-known family: a fixed place to ask “what can I call here?” with a parseable answer — the API-inventory complement to what an MCP manifest says about tools. No agent runtime is known to consume it automatically yet; it is a bet on the discovery layer, not a requirement of it.

A one-API catalog (linkset)

GET /.well-known/api-catalog        ← run this against your own site
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

{ "linkset": [ { "anchor": "https://developer.example.com/api",
    "item": [ { "href": "https://api.example.com/v1" } ],
    "service-desc": [ { "href": "https://developer.example.com/openapi.json" } ],
    "service-doc":  [ { "href": "https://developer.example.com/docs" } ] } ] }

How AgentGrade checks it

Not yet scored — api-catalog is specced in the scanner’s well-known discovery sweep and will start (like every emerging-standard check) at weight zero. The scanner already credits the adjacent surface: a discoverable OpenAPI description advertised via Link: rel="service-desc", which is the same relation this catalog uses per entry. Scan your site to see where you stand.

Related

All standards

RFC 9421 · Web Bot Auth · RFC 8615 · MCP · A2A · x402 · WebMCP · llms.txt · RFC 9309 · RFC 9110 · RFC 9116 · OAuth Discovery · RFC 7591 · RFC 9727 · ACP / UCP / AP2 · Index