Skip to content

CONCEPT Cited by 1 source

API Catalog

Definition

API Catalog is an IETF standard (RFC 9727, 2025) that defines a well-known URL at which a service publishes a JSON document listing all of its public APIs: links to specs (OpenAPI / AsyncAPI), docs, status endpoints, contact.

The well-known URL is /.well-known/api-catalog.

Why it exists

Agents working against an API need to discover it before they can use it. Pre-RFC-9727 discovery options were all unreliable:

  • Scrape the developer portal HTML — works sometimes, expensive in tokens, fragile across redesigns.
  • Search for an OpenAPI file at a guessed URL — /openapi.json, /swagger.json, /api-docs — no standard.
  • Ask the human to paste the spec URL — negates the autonomous-agent use case.

/.well-known/api-catalog gives one place to look, with structured data inside.

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"
    },
    ...
  ]
}

Plus an optional HTTP-header hint on any endpoint:

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

This uses the Link: response header per RFC 8288 to advertise the catalog without any HTML parsing.

Adoption (2026-04)

Per Cloudflare Radar on the top 200 k domains, /.well-known/api-catalog + MCP Server Cards combined appear on fewer than 15 sites in the entire dataset. Greenfield standard.

Relationship to MCP Server Cards

Different audiences:

  • API Catalog is for classical HTTP API consumers (humans, scripts, pre-LLM integrations). Points at OpenAPI / AsyncAPI specs + docs — human-readable + existing-tooling- compatible.
  • MCP Server Card is for LLM agents that speak MCP. Points at an MCP server definition including tools / transport / auth.

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

Seen in

Last updated · 200 distilled / 1,178 read