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.
Your catalog already knows where your APIs live. It knows which services expose OpenAPI, AsyncAPI, or GraphQL specifications. It knows which domains describe broader API surfaces.
EventCatalog can now turn that knowledge into a standard discovery endpoint at /.well-known/api-catalog.
Why this matters
Developers and agents should not need to crawl your docs site to find the contracts your team already publishes. They should be able to ask one known URL and get back a machine-readable answer.
That is the idea behind RFC 9727. It defines /.well-known/api-catalog as a standard place for discovering a publisher's APIs, specifications, and supporting documentation.
This is small, but useful. If your EventCatalog has service or domain specifications, tools can now discover them directly.
The problem
Most API discovery still starts with a human. Someone shares a docs link, points a teammate at a portal, or tells an agent which OpenAPI file to read.
That does not scale well when your architecture has many services, domains, and integration points. It gets worse when AI tools need to inspect your catalog without prior context.
The pattern is still early. API Evangelist recently looked at /.well-known/api-catalog adoption and found that only a handful of providers were publishing a real Linkset. That is exactly why this is useful for EventCatalog users: you can make your APIs discoverable from the catalog you already maintain, without building another portal or custom crawler.
What's new
EventCatalog can publish a Linkset at:
GET /.well-known/api-catalog
The response uses:
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"
The catalog includes EventCatalog resources that have API specifications attached. In the first version, that means services and domains with OpenAPI, AsyncAPI, or GraphQL specifications.
If your catalog has the EventCatalog MCP server enabled, the MCP endpoint is included too.
What it looks like
Here is a small example:
{
"linkset": [
{
"anchor": "https://api.example.com/orders",
"service-desc": [
{
"href": "https://catalog.example.com/.well-known/api-catalog/specifications/services/OrdersService/1.0.0/openapi",
"type": "application/yaml",
"title": "Orders Service OpenAPI"
}
],
"service-doc": [
{
"href": "https://catalog.example.com/docs/services/OrdersService/1.0.0.md",
"type": "text/markdown",
"title": "Orders Service documentation"
},
{
"href": "https://catalog.example.com/docs/services/OrdersService/1.0.0",
"type": "text/html",
"title": "Orders Service documentation"
}
]
},
{
"anchor": "https://catalog.example.com/docs/mcp",
"service-desc": [
{
"href": "https://catalog.example.com/docs/mcp",
"type": "application/json",
"title": "EventCatalog MCP Server"
}
]
}
]
}
The anchor points at the API endpoint when EventCatalog can derive one from your specification. For OpenAPI, that comes from servers[].url; for AsyncAPI, it comes from the servers object.
When EventCatalog cannot find an absolute API endpoint, it falls back to the EventCatalog documentation page. That keeps the catalog useful while still rewarding teams that keep endpoint metadata in their specs.
What is included
The first version stays intentionally focused.
Included:
- Services with
specifications - Domains with
specifications - OpenAPI, AsyncAPI, and GraphQL as
service-desc - Markdown and HTML documentation as
service-doc - EventCatalog MCP when enabled
Not included:
- Event, command, and query message schemas
- Data products, containers, diagrams, teams, and users
- Extra configuration switches
Message schemas matter, but they are not the same thing as API discovery. AsyncAPI is the better standards-aligned path for describing event-driven APIs in this endpoint.
When you would use it
Use this when you want API clients, internal tools, or coding agents to discover your architecture without bespoke instructions.
If your team publishes many APIs across domains, /.well-known/api-catalog gives you a small standard entrypoint into the catalog. If your agents need to know which OpenAPI or AsyncAPI files exist, this removes the first manual step.
It is also useful as a governance signal. A catalog that exposes its API surface in a standard format is easier to inspect, validate, monitor, and keep current.
Getting started
Add specifications to your services or domains as usual:
---
id: OrdersService
name: Orders Service
version: 1.0.0
specifications:
- type: openapi
path: openapi.yaml
---
Then open:
http://localhost:3000/.well-known/api-catalog
You should see a Linkset JSON document with any services or domains that publish specifications.
Summary
RFC 9727 gives API publishers a simple convention: one well-known URL, one machine-readable catalog, many discoverable APIs.
EventCatalog already has the source material for that catalog. This feature exposes it in a way that developer tools and agents can consume directly.
To try it, upgrade EventCatalog and open /.well-known/api-catalog in your catalog:
npm install @eventcatalog/core@latest