---
title: "Gerador de catálogo de APIs para /.well-known/api-catalog · DotsAgent"
description: "Gere o linkset JSON definido pela RFC 9727 para /.well-known/api-catalog, listando cada API com sua descrição OpenAPI, documentação e página de status, além de um bloco nginx."
url: https://dotsagent.io/pt/agent-ready/api-catalog
---

RFC 9727

# Gerador de catálogo de APIs

Liste suas APIs públicas uma vez e gere o linkset JSON exigido pela RFC 9727 em /.well-known/api-catalog, além de um bloco nginx para servi-lo com o tipo de mídia correto.

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

Envie o arquivo para /.well-known/api-catalog e sirva-o como application/linkset+json. O bloco nginx define esse tipo e adiciona um cabeçalho Link com rel="api-catalog", conforme exigido pela RFC 9727 em solicitações HEAD.

## Por que publicar um catálogo de APIs

Antes de chamar sua API, um agente precisa encontrá-la. Publicada em junho de 2025, a RFC 9727 define um ponto de partida fixo para essa busca: a URL conhecida /.well-known/api-catalog e a relação de link api-catalog, que qualquer página pode usar para apontar para ela.

O catálogo é um linkset em JSON. Cada entrada usa a URL base de uma API como âncora e aponta para sua descrição legível por máquina (service-desc, geralmente um arquivo OpenAPI), sua documentação para pessoas (service-doc) e sua página de status. Assim, o cliente lê um único arquivo pequeno em vez de rastrear sua documentação.

A RFC determina que a resposta use application/linkset+json e recomenda incluir o perfil https://www.rfc-editor.org/info/rfc9727. Ainda não temos dados sobre quais agentes solicitam o arquivo, mas basta publicar um único arquivo estático.

## Dúvidas sobre api-catalog

### O que é /.well-known/api-catalog?

É o local definido pela RFC 9727 para uma lista legível por máquina das APIs de uma organização. O arquivo é um linkset JSON que associa cada API à sua descrição, documentação e página de status. Os clientes podem encontrá-lo diretamente nesse endereço ou por meio da relação de link api-catalog.

### Qual Content-Type o api-catalog precisa usar?

A RFC 9727 determina o uso de application/linkset+json e recomenda incluir o parâmetro profile https://www.rfc-editor.org/info/rfc9727. O bloco nginx desta página define o tipo de mídia e o cabeçalho Link. Se a configuração do seu servidor permitir, adicione o parâmetro profile por conta própria.

### Preciso de um arquivo OpenAPI para publicar um catálogo?

Não. Neste gerador, cada entrada precisa apenas da URL base da API; os links para descrição, documentação e status são opcionais. Uma descrição OpenAPI permite que o cliente conheça seus endpoints sem ler documentação em prosa. Se você tiver uma, inclua-a.

### Qual é a diferença entre api-catalog e llms.txt?

api-catalog é uma RFC da IETF que lista APIs como links JSON para softwares que as chamam. llms.txt é uma proposta de índice em Markdown de páginas, voltada a modelos de linguagem que leem documentação. Eles têm finalidades diferentes, então você pode publicar ambos.

## Fontes

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

Referência independente para quem cria agentes de IA. Não temos vínculo com nenhum dos fornecedores mencionados aqui.

© 2026 DotsAgent · Fatos verificados em 1 de outubro de 2026