---
title: "API Catalog"
description: "Publish an RFC 9727 catalog so agents can discover your public APIs."
canonical_url: "https://nuxtseo.com/docs/ai-ready/guides/api-catalog"
last_updated: "2026-08-04T12:24:48.391Z"
---

[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html) defines a standard API discovery endpoint and `api-catalog` link relation. Enable it when your site publishes public APIs that agents should call.

When MCP Toolkit runs on the server, Nuxt AI Ready adds its endpoint and server card automatically. Set `apiCatalog: false` to suppress that generated entry.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  site: {
    url: 'https://example.com',
  },
  aiReady: {
    apiCatalog: {
      entries: [
        {
          anchor: '/api/v1',
          serviceDesc: {
            href: '/openapi.json',
            type: 'application/vnd.oai.openapi+json;version=3.1',
          },
          serviceDoc: {
            href: '/docs/api',
            type: 'text/html',
          },
          status: {
            href: '/api/health',
            type: 'application/json',
          },
        },
      ],
    },
  },
})
```

Nuxt AI Ready then:

- Serves `GET /.well-known/api-catalog` as `application/linkset+json` with the RFC 9727 profile
- Serves the same discovery headers for `HEAD /.well-known/api-catalog`, without a response body
- Adds `Link: <...>; rel="api-catalog"` to page responses
- Prerenders the catalog when the deployment prerenders routes

Relative `anchor` and `href` values resolve against the deployed site URL. With `app.baseURL: '/docs/'`, Nuxt redirects the origin-root well-known request to the base-aware handler and resolves `/api` as `https://example.com/docs/api`. Absolute URLs remain unchanged, so one catalog can describe APIs on other origins.

## Entries and Relations

An entry uses its `anchor` as the API endpoint or link context. It must contain at least one relation target. Targets accept either one object or an array.

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Linkset relation
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        item
      </code>
    </td>
    
    <td>
      <code>
        item
      </code>
    </td>
    
    <td>
      API endpoint belonging to the catalog
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        serviceDesc
      </code>
    </td>
    
    <td>
      <code>
        service-desc
      </code>
    </td>
    
    <td>
      Machine-readable description, commonly OpenAPI
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        serviceDoc
      </code>
    </td>
    
    <td>
      <code>
        service-doc
      </code>
    </td>
    
    <td>
      Human-readable documentation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        serviceMeta
      </code>
    </td>
    
    <td>
      <code>
        service-meta
      </code>
    </td>
    
    <td>
      Policies, licensing, or other metadata
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      Health or service status
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        apiCatalog
      </code>
    </td>
    
    <td>
      <code>
        api-catalog
      </code>
    </td>
    
    <td>
      Nested catalog
    </td>
  </tr>
</tbody>
</table>

Targets support `href`, `type`, `title`, `hreflang`, and `media`. Add registered relation tokens or absolute extension relation URIs through `relations`. `anchor` is reserved for the link context.

```ts
export default defineNuxtConfig({
  aiReady: {
    apiCatalog: {
      entries: [{
        anchor: '/api',
        relations: {
          license: { href: '/legal/api-license', type: 'text/html' },
        },
      }],
    },
  },
})
```

Keep the catalog limited to public APIs. RFC 9727 recommends a security and privacy review before publishing it.