---
title: "API-catalogusgenerator voor /.well-known/api-catalog · DotsAgent"
description: "Genereer de JSON-linkset volgens RFC 9727 voor /.well-known/api-catalog. Vermeld elke API met de OpenAPI-specificatie, documentatie en statuspagina, plus een nginx-blok."
url: https://dotsagent.io/nl/agent-ready/api-catalog
---

RFC 9727

# API-catalogusgenerator

Vermeld je openbare API's één keer en genereer de JSON-linkset die RFC 9727 voorschrijft voor /.well-known/api-catalog, plus een nginx-blok dat het bestand met het juiste mediatype serveert.

`/.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 het bestand naar /.well-known/api-catalog en serveer het als application/linkset+json. Het nginx-blok stelt dit mediatype in en voegt een Link-header met rel="api-catalog" toe, zoals RFC 9727 voorschrijft voor HEAD-verzoeken.

## Waarom een API-catalogus publiceren

Een agent moet je API eerst kunnen vinden voordat die deze kan aanroepen. RFC 9727, gepubliceerd in juni 2025, biedt daarvoor een vast startpunt: de well-known-URL /.well-known/api-catalog en de api-catalog-linkrelatie waarmee elke pagina ernaar kan verwijzen.

De catalogus is een linkset in JSON. Elke vermelding is gekoppeld aan de basis-URL van een API en verwijst naar de machineleesbare beschrijving (service-desc, meestal een OpenAPI-bestand), de documentatie voor mensen (service-doc) en de statuspagina. Een client leest één klein bestand in plaats van je documentatie te crawlen.

Volgens de RFC moet het antwoord application/linkset+json gebruiken en hoort het het profiel https://www.rfc-editor.org/info/rfc9727 te bevatten. We weten nog niet welke agents het bestand opvragen, maar het is slechts één statisch bestand dat je hoeft te publiceren.

## Vragen over api-catalog

### Wat is /.well-known/api-catalog?

Dit is de locatie die RFC 9727 definieert voor een machineleesbare lijst van de API's van een organisatie. Het bestand is een JSON-linkset die elke API koppelt aan de beschrijving, documentatie en statuspagina. Clients kunnen het bestand daar rechtstreeks vinden of via de api-catalog-linkrelatie.

### Welke Content-Type heeft api-catalog nodig?

Volgens RFC 9727 moet dit application/linkset+json zijn en hoort de profielparameter https://www.rfc-editor.org/info/rfc9727 erbij. Het nginx-blok op deze pagina stelt het mediatype en de Link-header in. Voeg de profielparameter zelf toe als je serverconfiguratie dat ondersteunt.

### Heb ik een OpenAPI-bestand nodig om een catalogus te publiceren?

Nee. In deze generator heeft elke vermelding alleen de basis-URL van de API nodig; links naar de beschrijving, documentatie en statuspagina zijn optioneel. Met een OpenAPI-specificatie kan een client je endpoints ontdekken zonder documentatie te hoeven lezen. Voeg er dus een toe als je die hebt.

### Wat is het verschil tussen api-catalog en llms.txt?

api-catalog is een RFC van de IETF die API's als JSON-links vermeldt voor software die ze aanroept. llms.txt is een voorstel voor een Markdown-index van pagina's, bedoeld voor taalmodellen die documentatie lezen. Ze overlappen elkaar niet, dus je kunt beide publiceren.

## Bronnen

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

Onafhankelijke referentie voor iedereen die AI-agents bouwt. Niet verbonden aan een van de genoemde leveranciers.

© 2026 DotsAgent · Feiten gecontroleerd op 1 oktober 2026