---
name: api-catalog
description: Expose a /.well-known/api-catalog (RFC 9727) describing your APIs
---

# API Catalog (RFC 9727)

Publish a machine-readable index of your APIs at `/.well-known/api-catalog`.

## Requirements

- Serve `/.well-known/api-catalog` with HTTP 200
- Content-Type: `application/linkset+json`
- Body has a `linkset` array; each entry has an `anchor` URL and link relations:
  - `service-desc` — OpenAPI / spec URL
  - `service-doc` — human docs URL
  - `status` — health endpoint

## Example

```json
{
  "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://docs.example.com/api/v1", "type": "text/html" }],
      "status":       [{ "href": "https://api.example.com/v1/health", "type": "application/json" }]
    }
  ]
}
```

## References

- [RFC 9727 — API Catalog](https://www.rfc-editor.org/rfc/rfc9727)
- [RFC 9264 — Linkset](https://www.rfc-editor.org/rfc/rfc9264)