---
title: "Générateur de catalogue d’API pour /.well-known/api-catalog · DotsAgent"
description: "Générez l’ensemble de liens JSON défini par la RFC 9727 pour /.well-known/api-catalog. Répertoriez chaque API avec sa description OpenAPI, sa documentation et sa page d’état, et obtenez un bloc nginx."
url: https://dotsagent.io/fr/agent-ready/api-catalog
---

RFC 9727

# Générateur de catalogue d’API

Répertoriez vos API publiques une seule fois et obtenez l’ensemble de liens JSON attendu par la RFC 9727 à l’adresse /.well-known/api-catalog, ainsi qu’un bloc nginx pour le servir avec le type MIME approprié.

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

Envoyez le fichier à l’adresse /.well-known/api-catalog et servez-le avec le type application/linkset+json. Le bloc nginx définit ce type et ajoute un en-tête Link avec rel="api-catalog", attendu par la RFC 9727 dans les requêtes HEAD.

## Pourquoi publier un catalogue d’API

Un agent qui veut appeler votre API doit d’abord la trouver. Publiée en juin 2025, la RFC 9727 définit un point de départ fixe pour cette recherche : l’URL bien connue /.well-known/api-catalog, ainsi que la relation de lien api-catalog, que n’importe quelle page peut utiliser pour y renvoyer.

Le catalogue est un ensemble de liens au format JSON. Chaque entrée est ancrée sur l’URL de base d’une API et renvoie vers sa description lisible par machine (service-desc, généralement un fichier OpenAPI), sa documentation destinée aux utilisateurs (service-doc) et sa page d’état. Un client peut ainsi lire un petit fichier au lieu d’explorer votre documentation.

La RFC indique que la réponse doit utiliser le type application/linkset+json et devrait inclure le profil https://www.rfc-editor.org/info/rfc9727. Nous ne savons pas encore quels agents demandent ce fichier, mais il suffit de publier un fichier statique.

## Questions sur api-catalog

### Qu’est-ce que /.well-known/api-catalog ?

C’est l’emplacement défini par la RFC 9727 pour une liste lisible par machine des API d’une organisation. Le fichier est un ensemble de liens JSON qui relie chaque API à sa description, sa documentation et sa page d’état. Les clients peuvent le trouver directement à cet emplacement ou via la relation de lien api-catalog.

### Quel Content-Type faut-il pour api-catalog ?

La RFC 9727 indique qu’il doit être application/linkset+json et devrait inclure le paramètre profile https://www.rfc-editor.org/info/rfc9727. Le bloc nginx de cette page définit le type MIME et l’en-tête Link ; ajoutez vous-même le paramètre profile si la configuration de votre serveur le permet.

### Faut-il un fichier OpenAPI pour publier un catalogue ?

Non. Dans ce générateur, chaque entrée nécessite uniquement l’URL de base de l’API ; les liens vers la description, la documentation et la page d’état sont facultatifs. Une description OpenAPI permet à un client de découvrir vos endpoints sans devoir lire de documentation en prose : ajoutez-en une si vous en avez une.

### Quelle est la différence entre api-catalog et llms.txt ?

api-catalog est une RFC de l’IETF qui répertorie des API sous forme de liens JSON pour les logiciels qui les appellent. llms.txt est une proposition d’index Markdown des pages, destinée aux modèles de langage qui consultent la documentation. Ces formats ne se recoupent pas : vous pouvez donc publier les deux.

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

Référence indépendante pour les personnes qui créent des agents IA. Sans affiliation avec les fournisseurs cités.

© 2026 DotsAgent · Données vérifiées le 1 octobre 2026