---
title: "API catalog generator for /.well-known/api-catalog · DotsAgent"
description: "Build the RFC 9727 JSON linkset for /.well-known/api-catalog, listing each API with its OpenAPI description, docs and status page, plus an nginx block."
url: https://dotsagent.io/agent-ready/api-catalog
---

RFC 9727

# 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.

`/.well-known/api-catalog`

```
{
  "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"
        }
      ]
    }
  ]
}
```

`nginx`

```
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.

## Sources

1. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9727)/rfc/rfc9727
2. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9264)/rfc/rfc9264
3. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc8631)/rfc/rfc8631

Independent reference for people who build AI agents. Not affiliated with any vendor named here.

© 2026 DotsAgent · Facts checked October 1, 2026