# api-catalog

## What is API Catalog?

**API Catalog** (RFC 9727) is a linkset-format JSON document at `/.well-known/api-catalog` that lists all public APIs on a site. It lets AI agents automatically discover available APIs without parsing documentation.

```json
{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }]
    }
  ]
}
```

The `Content-Type` must be `application/linkset+json`.

## Why do you need API Catalog?

AI agents operating autonomously need to find API entry points. API Catalog is the canonical place for this: an agent does a GET `/.well-known/api-catalog` and receives a complete list of available resources with their documentation.

A link to the API Catalog should also appear in [Link headers](/glossary/link-headers) on the home page:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"
```

## How do you implement API Catalog?

Create a file `public/.well-known/api-catalog` with `Content-Type: application/linkset+json`. The structure per RFC 9727 is a `linkset` array where each element contains:

| Field | Required | Description |
|-------|----------|-------------|
| `anchor` | yes | URI of the API resource |
| `service-doc` | recommended | Link to documentation (OpenAPI, Swagger) |
| `service-desc` | recommended | Link to machine-readable schema |
| `status` | no | API status (`stable`, `deprecated`) |

For OAuth-protected APIs, add a link to authorization metadata:

```json
{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }],
      "oauth-protected-resource": [{ "href": "https://api.example.com/.well-known/oauth-protected-resource" }]
    }
  ]
}
```

## How do we check API Catalog?

The scanner performs a GET `/.well-known/api-catalog` with the header `Accept: application/linkset+json, application/json` and verifies:

1. HTTP status 200 and `Content-Type` of `application/linkset+json` or `application/json`
2. Valid JSON with a root `linkset` array
3. Non-empty `linkset` — at least one element with both `anchor` and `href`

Gradient scoring: 3+ valid elements → `pass` (1.0), 1–2 → `warning` (0.5), 0 → `fail`.

[← All glossary terms](/en/glossary)