---
title: "Генератор каталога API для /.well-known/api-catalog · DotsAgent"
description: "Создайте JSON linkset по RFC 9727 для /.well-known/api-catalog: укажите для каждого API описание OpenAPI, документацию и страницу статуса, а также получите блок nginx."
url: https://dotsagent.io/ru/agent-ready/api-catalog
---

RFC 9727

# Генератор каталога API

Перечислите публичные API и получите JSON linkset, который RFC 9727 требует размещать по адресу /.well-known/api-catalog, а также блок 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 задаёт этот тип и добавляет заголовок Link с rel="api-catalog", который RFC 9727 требует для запросов HEAD.

## Зачем публиковать каталог API

Агенту, который хочет вызвать ваш API, сначала нужно его найти. RFC 9727, опубликованный в июне 2025 года, задаёт для поиска стандартную точку входа: well-known URL /.well-known/api-catalog и отношение ссылки api-catalog, с помощью которого на него может указывать любая страница.

Каталог представляет собой linkset в формате JSON. Каждая запись привязана к базовому URL API и содержит ссылки на его машиночитаемое описание (service-desc, обычно файл OpenAPI), документацию для людей (service-doc) и страницу статуса. Клиенту достаточно прочитать один небольшой файл вместо обхода документации.

Согласно RFC, ответ должен иметь тип application/linkset+json и рекомендуется указывать профиль https://www.rfc-editor.org/info/rfc9727. Пока неизвестно, какие агенты запрашивают этот файл, но для публикации достаточно одного статического файла.

## Вопросы о api-catalog

### Что такое /.well-known/api-catalog?

Это адрес, определённый RFC 9727 для машиночитаемого списка API организации. Файл представляет собой JSON linkset со ссылками от каждого API на его описание, документацию и страницу статуса. Клиенты могут найти его напрямую по этому адресу или через отношение ссылки api-catalog.

### Какой Content-Type нужен для api-catalog?

RFC 9727 указывает, что тип должен быть application/linkset+json, а в параметре profile рекомендуется передавать https://www.rfc-editor.org/info/rfc9727. Блок nginx на этой странице задаёт тип содержимого и заголовок Link. Если конфигурация сервера это позволяет, добавьте параметр profile самостоятельно.

### Нужен ли файл OpenAPI для публикации каталога?

Нет. В этом генераторе для каждой записи нужен только базовый URL API; ссылки на описание, документацию и страницу статуса необязательны. Описание OpenAPI позволяет клиенту узнать о ваших endpoints, не читая текстовую документацию, поэтому добавьте его, если оно у вас есть.

### Чем api-catalog отличается от llms.txt?

api-catalog — это стандарт IETF RFC, который перечисляет API в виде 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-агентов. Не связан ни с одним из упомянутых здесь поставщиков.

© 2026 DotsAgent · Факты проверены 1 октября 2026 г.