agenticweb.wiki

api-catalog (RFC 9727)

Last checked · 18 primary sources

This page is about RFC 9727, the IETF standard that defines the /.well-known/api-catalog URI and the "api-catalog" link relation for listing a publisher’s APIs. It is not the agent-specific AI Catalog well-known file (/.well-known/ai-catalog.json), and not a product such as an internal developer-portal "API catalog". For agent and MCP discovery files, see Agentic Resource Discovery (ARD) and MCP Server Cards.

Overview

RFC 9727 gives a publisher one predictable address, /.well-known/api-catalog, that returns a machine-readable list of its public APIs, plus an "api-catalog" link relation that can point to a catalog kept anywhere else [1]. The catalog is a Linkset document (application/linkset+json, defined in RFC 9264): "item" links name each API in the catalog, other link relations such as service-desc (for example an OpenAPI file), service-doc and status carry metadata, and a catalog can link to further catalogs with the api-catalog relation [1][11]. It does not replace API description formats such as OpenAPI, which the catalog links to, and a publisher may also serve another catalog format such as APIs.json by content negotiation, as long as the Linkset form is available [1]. The RFC is not specific to AI agents, but Cloudflare’s agent-readiness checker now tests for it alongside agent-specific files such as MCP Server Cards [12].

Who uses it

Each URL below returned HTTP 200 with no redirect on 2026-10-28, with the content-type shown and a JSON body whose top-level member is "linkset". The text in code style is the start of the response body, up to the first link target (whitespace collapsed). "HEAD Link" says whether a HEAD request to the same URL returned a Link header with rel="api-catalog", which the RFC requires [1]. These five are examples, not a complete list: many more sites served a linkset at this path when checked the same day.

Who reads it

Tools that generate or publish the file (they write it, they do not read it):

No statement found as of 2026-10-28 from an AI agent or assistant vendor (for example Anthropic, OpenAI, Google, Microsoft or Cursor) saying its agent fetches /.well-known/api-catalog. On 2026-07-22 Dries Buytaert, who logs requests to the file on his site, wrote: "The result so far: zero AI agents have used it." [16]

Recent coverage

See also

References

  1. K. Smith (Vodafone), RFC 9727: api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs, IETF, Standards Track, June 2025: "This document defines the "api-catalog" well-known URI and link relation." "It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs)." "This is an Internet Standards Track document." "This document is a product of the Internet Engineering Task Force (IETF)." "Author: K. Smith Vodafone" "SHALL resolve an HTTPS GET request to /.well-known/api-catalog and return an API catalog document (as described in Section 4)." "SHALL resolve an HTTPS HEAD request to /.well-known/api-catalog with a response including a Link header with the relation(s) defined in Section 3." "Link: </my_api_catalog.json>; rel=api-catalog" "When used in an API catalog document, the "item" [RFC6573] link relation identifies a target resource that represents an API that is a member of the API catalog." "The API catalog MUST include hyperlinks to API endpoints." "The Publisher MUST publish the API catalog document in the Linkset format application/linkset+json (Section 4.2 of [RFC9264])." "The Linkset SHOULD include a profile parameter (Section 5 of [RFC9264]) with a Profile URI [RFC7284] value of "https://www.rfc-editor.org/info/rfc9727" to indicate the Linkset is representing an API catalog document as defined above." "An API catalog may itself contain links to other API catalogs by using the "api-catalog" relation type for each link." "A /.well-known/api-catalog location MUST support the Linkset [RFC9264] format of application/linkset+json and MAY also support the other formats via content negotiation." "An APIs.json document [APIsjson]." — https://www.rfc-editor.org/rfc/rfc9727.html
  2. IETF Datatracker, RFC 9727 document page, checked 2026-10-28: "RFC - Proposed Standard (June 2025)" "Was draft-ietf-httpapi-api-catalog (httpapi WG)" — https://datatracker.ietf.org/doc/rfc9727/
  3. IETF Datatracker, RFC 9727 document history, checked 2026-10-28: "2025-06-13 (System) RFC published" — https://datatracker.ietf.org/doc/rfc9727/history/
  4. IETF Datatracker, draft-ietf-httpapi-api-catalog history (revision list), checked 2026-10-28: "draft-smith-api-catalog-00 (2023-05-04)" "draft-ietf-httpapi-api-catalog-00 (2023-09-12)" — https://datatracker.ietf.org/doc/draft-ietf-httpapi-api-catalog/history/
  5. K. Smith, Ed. (Vodafone), draft-smith-api-catalog-00 (individual Internet-Draft), 4 May 2023: "Published: 4 May 2023" "This document defines the "api-catalog" well-known URI. It is intended to facilitate discovery of the APIs published by a Web host." — https://datatracker.ietf.org/doc/html/draft-smith-api-catalog-00
  6. RFC Editor, RFC Errata search results for RFC 9727, checked 2026-10-28: "Errata-ID: 9009 Status: Reported Type: Technical" "Date Reported: 2026-06-21" — https://errata.rfc-editor.org/search/?rfc_number=9727&presentation=records
  7. IANA, Well-Known URIs registry (registry last updated 2026-10-26), checked 2026-10-28; row quoted from the registry’s CSV export (well-known-uris-1.csv): "api-catalog,[RFC 9727],permanent,IETF,,2024-12-23," — https://www.iana.org/assignments/well-known-uris
  8. IANA, Link Relation Types registry (registry last updated 2026-06-12), checked 2026-10-28; row quoted from the registry’s CSV export (link-relations-1.csv): "api-catalog,Refers to a list of APIs available from the Publisher of the link context.,[RFC 9727]," — https://www.iana.org/assignments/link-relations
  9. IANA, Profile URIs registry (registry last updated 2026-10-05), checked 2026-10-28; row text as rendered: "https://www.rfc-editor.org/info/rfc9727 API catalog A profile URI to request or signal a Linkset representing an API catalog." — https://www.iana.org/assignments/profile-uris
  10. IANA, application/linkset+json media type registration template, checked 2026-10-28: "Subtype name: linkset+json" "Optional parameters: profile" "Published specification: [RFC9264]" — https://www.iana.org/assignments/media-types/application/linkset+json
  11. E. Wilde and H. Van de Sompel, RFC 9264: Linkset: Media Types and a Link Relation Type for Link Sets, IETF, July 2022: "This specification defines two formats and associated media types for representing sets of links as standalone documents." — https://www.rfc-editor.org/rfc/rfc9264.html
  12. André Jesus and Vance Morrison, Cloudflare, Introducing the Agent Readiness score. Check to see if your site is agent-ready (Cloudflare Blog), 2026-04-17: "When you enter your site, Cloudflare makes requests to it to check which standards it supports, and provides a score based on four dimensions:" "Capabilities: Agent Skills, API Catalog (RFC 9727), OAuth server discovery via RFC 8414 and RFC 9728, MCP Server Card, and WebMCP" "If your service has one or more public APIs, the API Catalog (RFC 9727) gives agents a single well-known location to discover all of them." — https://blog.cloudflare.com/agent-readiness/
  13. Xuantong Liu, IBM, Introducing API Catalog Support in IBM API Connect CMS Portal in v12.1.0.0 (IBM TechXchange Community blog), posted 2025-12-16 (the URL path shows 2025/10/13): "IBM API Connect CMS Portal now supports a new API Catalog module that allows your APIs to be exposed in a standardized, discoverable format." "This feature is based on RFC 9727, which defines a linkset format for listing APIs in a machine-readable way." — https://community.ibm.com/community/user/blogs/xuantong-liu/2025/10/13/introducing-api-catalog-support-in-ibm-api-connect
  14. David Boyne, EventCatalog, Let tools find your APIs from one URL (EventCatalog blog), 2026-05-25: "EventCatalog can now publish an API catalog at /.well-known/api-catalog, giving agents and developer tools one machine-readable place to discover your service, domain, and MCP API surfaces." — https://www.eventcatalog.dev/blog/api-catalog
  15. Cloudflare, pull request #30197 "feat: publish API catalog for automated discovery (RFC 9727)" in cloudflare/cloudflare-docs, merged 2026-04-22 22:20 UTC (text checked through the GitHub API): "This allows agents, SDK generators, and other tooling to discover Cloudflare’s API without any human involvement." — https://github.com/cloudflare/cloudflare-docs/pull/30197
  16. Dries Buytaert, Helping agents discover my site search with an API Catalog (dri.es), 2026-07-22: "RFC 9727, an IETF Proposed Standard, defines /.well-known/api-catalog as a predictable location for discovering a site’s public APIs." "The result so far: zero AI agents have used it." "I recently created an Agent Skill, a SKILL.md file that directs my agents to check the catalog and use my site’s search API whenever they need information from dri.es." — https://dri.es/helping-agents-discover-my-site-search-with-an-api-catalog
  17. Kin Lane, API Evangelist, Only Four API Providers Publish a Real .well-known/api-catalog Right Now, 2026-05-22: "RFC 9727 has been a published IETF standard for over a year." "Four providers serve a real RFC 9727 LinkSet at /.well-known/api-catalog:" — https://apievangelist.com/blog/2026/05/22/four-providers-publishing-well-known-api-catalog/
  18. AgentScan, /.well-known/ for agents: the 2026 reference, 2026-05-10 (no author named): "A single linkset+json document listing every public API the publisher exposes. The agent equivalent of a sitemap for APIs." — https://agentscan.devmahmoud.me/blog/well-known-uris-for-agents

JSON · Markdown · OKF v0.2