# api-catalog

Copy as Markdown[View as Markdown](/docs/development/developer-tools/api-catalog.md)

***

**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?[​](#what-is-rfc-9727 "Direct link to What is RFC 9727?")

[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) defines the `/.well-known/api-catalog` well-known URI. It returns a [Linkset](https://www.rfc-editor.org/rfc/rfc9264) 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[​](#how-it-works "Direct link to 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[​](#access-the-endpoint "Direct link to 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[​](#fetch-a-specification-file "Direct link to 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[​](#mcp-server-entry "Direct link to 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[​](#what-is-included "Direct link to 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](/docs/development/developer-tools/llms.txt.md) and [schemas.txt](/docs/development/developer-tools/schemas.txt.md).