api-catalog

View as Markdown

---

Added in eventcatalog@3.42.0

Let API tools, agents, and crawlers discover every service and domain specification in your catalog from a single endpoint, without parsing HTML.

What is RFC 9727?

RFC 9727 defines the /.well-known/api-catalog well-known URI. It returns a Linkset document that lists every API an organization publishes along with links to their specifications and documentation.

Tools that understand RFC 9727 can point at your catalog URL and immediately enumerate all services and domains, their OpenAPI, AsyncAPI, and GraphQL specs, and their documentation pages. No scraping required.

How it works

EventCatalog automatically publishes a Linkset at /.well-known/api-catalog. Every service and domain that has specifications defined in its frontmatter appears as an entry.

Each entry contains:

• anchor - the canonical URL of the service. EventCatalog reads the servers[].url field from OpenAPI or AsyncAPI specs and uses that. When no server URL is found it falls back to the EventCatalog documentation page.
• service-desc - one link per specification file, pointing at /.well-known/api-catalog/specifications/{collection}/{id}/{version}/{type} with the correct media type (application/yaml, application/json, or application/graphql).
• service-doc - two links per resource: the markdown source and the rendered HTML page.

Resources marked hidden: true are excluded from the linkset.

Access the endpoint

GET  /.well-known/api-catalog
HEAD /.well-known/api-catalog

The GET response body is application/linkset+json profiled against RFC 9727:

{
  "linkset": [
    {
      "anchor": "https://api.example.com/orders",
      "service-desc": [
        {
          "href": "https://catalog.example.com/.well-known/api-catalog/specifications/services/OrderService/1.0.0/openapi",
          "type": "application/yaml",
          "title": "Order Service OpenAPI"
        }
      ],
      "service-doc": [
        {
          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0.md",
          "type": "text/markdown",
          "title": "Order Service documentation"
        },
        {
          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0",
          "type": "text/html",
          "title": "Order Service documentation"
        }
      ]
    }
  ]
}

The HEAD response includes a Link header so clients can confirm the endpoint exists before fetching the full body:

Link: <https://catalog.example.com/.well-known/api-catalog>; rel="api-catalog"

Fetch a specification file

The raw specification files referenced in service-desc are served from:

GET /.well-known/api-catalog/specifications/{collection}/{id}/{version}/{type}

Segment	Values
collection	services, domains
id	The resource id field
version	The resource version field
type	openapi, asyncapi, graphql

Example:

GET /.well-known/api-catalog/specifications/services/OrderService/1.0.0/openapi
Content-Type: application/yaml

MCP server entry

When the EventCatalog MCP server is enabled, an additional entry pointing at /docs/mcp is appended to the linkset. This lets MCP-aware agents discover the catalog's machine interface alongside its API specifications.

What is included

Only services and domains are included in v1 of this endpoint. Events, commands, queries, data products, schemas, diagrams, teams, and users are out of scope for this release.

For a broader machine-readable index of your catalog content, see llms.txt and schemas.txt.