API catalog generator
List your public APIs once and get the JSON linkset that RFC 9727 expects at /.well-known/api-catalog, with an nginx block that serves it under the right media type.
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [
{
"href": "https://api.example.com/v1/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://example.com/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://status.example.com"
}
]
}
]
}
location = /.well-known/api-catalog {
default_type application/linkset+json;
add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
try_files /.well-known/api-catalog =404;
}
Upload the file to /.well-known/api-catalog and serve it as application/linkset+json. The nginx block sets that type and adds a Link header with rel="api-catalog", which RFC 9727 expects on HEAD requests.
Why publish an API catalog
An agent that wants to call your API first has to find it. RFC 9727, published in June 2025, gives that search a fixed starting point: the well-known URL /.well-known/api-catalog, plus an api-catalog link relation that any page can use to point at it.
The catalog is a linkset in JSON. Each entry anchors on an API's base URL and links to its machine-readable description (service-desc, usually an OpenAPI file), its human documentation (service-doc) and its status page. A client reads one small file instead of crawling your docs.
The RFC says the response must use application/linkset+json and should carry the profile https://www.rfc-editor.org/info/rfc9727. We have no data yet on which agents request the file, but it is a single static file to publish.
Questions about api-catalog
What is /.well-known/api-catalog?
It is the location RFC 9727 defines for a machine-readable list of an organisation's APIs. The file is a JSON linkset that points from each API to its description, documentation and status. Clients can find it there directly or through the api-catalog link relation.
What Content-Type does api-catalog need?
RFC 9727 says it must be application/linkset+json and should carry the profile parameter https://www.rfc-editor.org/info/rfc9727. The nginx block on this page sets the media type and the Link header; add the profile parameter yourself if your server setup allows it.
Do I need an OpenAPI file to publish a catalog?
No. In this generator each entry needs only the API's base URL, and the description, docs and status links are optional. An OpenAPI description is what lets a client learn your endpoints without reading prose, so add it when you have one.
How is api-catalog different from llms.txt?
api-catalog is an IETF RFC that lists APIs as JSON links for software that calls them. llms.txt is a proposal for a Markdown index of pages, aimed at language models reading docs. They don't overlap, so you can publish both.