---
title: "/.well-known/api-catalog 的 API catalog 生成器 · DotsAgent"
description: "为 /.well-known/api-catalog 生成符合 RFC 9727 的 JSON linkset，列出各个 API 的 OpenAPI 描述、文档和状态页，并提供 nginx 配置块。"
url: https://dotsagent.io/zh/agent-ready/api-catalog
---

RFC 9727

# API catalog 生成器

只需列出公开 API，即可生成 RFC 9727 要求放在 /.well-known/api-catalog 的 JSON linkset，以及一段通过正确媒体类型提供该文件的 nginx 配置块。

`/.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;
}
```

将文件上传到 /.well-known/api-catalog，并以 application/linkset+json 提供。nginx 配置块会设置该媒体类型，并添加带有 rel="api-catalog" 的 Link 标头，这是 RFC 9727 对 HEAD 请求的要求。

## 为什么要发布 API catalog

想调用你的 API 的 agent，首先必须找到它。RFC 9727 于 2025 年 6 月发布，为查找 API 提供了固定入口：知名 URL /.well-known/api-catalog，以及任何页面都可以用来指向该入口的 api-catalog link relation。

catalog 是一个 JSON linkset。每个条目以 API 的基础 URL 为锚点，并链接到机器可读的描述（service-desc，通常是 OpenAPI 文件）、面向用户的文档（service-doc）和状态页。客户端只需读取一个小文件，无须爬取你的文档。

RFC 规定响应必须使用 application/linkset+json，并建议携带 profile https://www.rfc-editor.org/info/rfc9727。目前还没有数据表明哪些 agent 会请求此文件，不过发布它只需要提供一个静态文件。

## 关于 api-catalog 的常见问题

### /.well-known/api-catalog 是什么？

这是 RFC 9727 为机器可读的组织 API 列表定义的位置。该文件是一个 JSON linkset，包含从各个 API 指向其描述、文档和状态页的链接。客户端可以直接从此处获取，也可以通过 api-catalog link relation 找到它。

### api-catalog 需要使用什么 Content-Type？

RFC 9727 规定必须使用 application/linkset+json，并建议携带 profile 参数 https://www.rfc-editor.org/info/rfc9727。本页的 nginx 配置块会设置媒体类型和 Link 标头；如果服务器配置允许，请自行添加 profile 参数。

### 发布 catalog 一定需要 OpenAPI 文件吗？

不需要。使用此生成器时，每个条目只需填写 API 的基础 URL；描述、文档和状态页链接都是可选的。OpenAPI 描述可以让客户端无需阅读文字说明就了解你的端点，因此如果已有 OpenAPI 描述，建议添加。

### api-catalog 与 llms.txt 有什么区别？

api-catalog 是一项 IETF RFC，用 JSON 链接列出供软件调用的 API。llms.txt 则是一项提案，用于创建面向阅读文档的语言模型的 Markdown 页面索引。两者用途不同，可以同时发布。

## 来源

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

为 AI agent 开发者提供的独立参考资料。与此处提及的任何厂商均无关联。

© 2026 DotsAgent · 事实核查日期：2026年10月1日