Skip to content

SYSTEM Cited by 1 source

API Catalog (RFC 9727)

Overview

API Catalog (RFC 9727, published 2025) is an IETF standard that specifies a fixed well-known URL — /.well-known/api-catalog — at which a service publishes a single JSON document listing all its public APIs, with links to specs (OpenAPI / AsyncAPI), documentation pages, status endpoints, and contact information.

The spec is short and deliberate — just enough structure for a client to discover "what APIs does this service offer, and where do I go to learn about each?"

What it replaces

Before RFC 9727, "all of this service's APIs" had no standard location. Clients had to:

  • Guess at likely URLs (/openapi.json, /swagger.json, /api-docs, /apis, …).
  • Scrape developer-portal HTML for links, fragile across redesigns.
  • Ask a human to paste the spec URL.

RFC 9727 pins a single path per service that clients can consult without negotiation. The HTTP response is plain JSON — no content negotiation, no auth dance, no protocol overhead beyond one GET.

Shape

{
  "apis": [
    {
      "name": "Pricing API",
      "description": "Query product pricing and availability",
      "spec-url": "https://api.example.com/specs/pricing.openapi.json",
      "docs-url": "https://developers.example.com/pricing"
    }
  ]
}

Additionally, any endpoint can advertise the catalog's presence via the Link: HTTP response header per RFC 8288:

HTTP/1.1 200 OK
Link: </.well-known/api-catalog>; rel="api-catalog"

— so an agent arriving mid-site can find the catalog without walking up to the origin root first.

Adoption (2026-04)

Per Cloudflare Radar on the top 200 k domains, RFC 9727 + MCP Server Card combined appear on fewer than 15 sites across the entire dataset. Positioned explicitly in the 2026 Agent Readiness Score post as an early-adopter opportunity surface.

Relationship to MCP Server Card

Two different audiences:

  • API Catalog (RFC 9727) for REST / HTTP API consumers — agents, scripts, classical integrations, OpenAPI tooling.
  • MCP Server Card for LLM agents speaking the Model Context Protocol — different wire format, different schema, different well-known path.

A service with both HTTP APIs and an MCP server should publish both — one /.well-known/api-catalog and one /.well-known/mcp/server-card.json.

Seen in

Last updated · 200 distilled / 1,178 read