---
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-10-04T10:01:46.471Z"
---

[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html) defines a standard API discovery endpoint and `api-catalog`{lang="http"} link relation. Use it to list your API endpoints and their documentation.

When MCP Toolkit runs on the server and `site.url` is set, Nuxt AI Ready adds its endpoint automatically.
The entry also links its server card when enabled. Set `apiCatalog: false`{lang="ts"} to disable the catalog.

```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',
          },
        },
      ],
    },
  },
})
```

With this configuration, the module:

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

Relative `anchor`{lang="ts"} and `href`{lang="ts"} values resolve against the deployed site URL.
With `app.baseURL: '/docs/'`{lang="ts"}, `/api` resolves to `https://example.com/docs/api`.
Nuxt redirects origin-root discovery requests to the handler under that base path.
Absolute URLs stay unchanged, including URLs on other origins.

## Entries and Relations

Use `anchor`{lang="ts"} for the API endpoint or link context. Add at least one relation target.
Each relation accepts one target object or an array of targets.

| Option        | Linkset relation | Use                                            |
| ------------- | ---------------- | ---------------------------------------------- |
| `item`        | `item`           | API endpoint belonging to the catalog          |
| `serviceDesc` | `service-desc`   | Machine-readable description, commonly OpenAPI |
| `serviceDoc`  | `service-doc`    | Human-readable documentation                   |
| `serviceMeta` | `service-meta`   | Policies, licensing, or other metadata         |
| `status`      | `status`         | Health or service status                       |
| `apiCatalog`  | `api-catalog`    | Nested catalog                                 |

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

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

Publish only APIs you intend clients to discover. Check endpoint access controls before adding them to the catalog.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.