---
title: API reference
description: Add API reference sections by connecting OpenAPI sources in docs.json navigation.
---

Radiant can generate API reference pages from OpenAPI sources. Use this when
you want endpoint documentation, request and response details, and playground
behavior to stay aligned with your API specification.

OpenAPI reference pages also improve Knowledge Assistant answers about exact methods, paths,
parameters, request bodies, responses, and errors.

## OpenAPI sources

OpenAPI sources can be:

- Local `.json`, `.yaml`, or `.yml` files inside the docs root.
- Public `http://` or `https://` URLs that return OpenAPI JSON or YAML.

Local OpenAPI paths are relative to the docs root and should not start with `/`.

```txt
docs.json
openapi.json
api/
  admin.openapi.yaml
```

## Generate a full API reference

Use top-level OpenAPI navigation when the docs site is primarily an API
reference:

```json
{
  "navigation": {
    "openapi": "openapi.json"
  }
}
```

Use an object when you need filters:

```json
{
  "navigation": {
    "openapi": {
      "source": "openapi.json",
      "include": ["GET /customers", "POST /customers"]
    }
  }
}
```

`include` and `exclude` are mutually exclusive. Use endpoint strings in the
`METHOD /path` format.

## Add API reference to a menu

Use `navigation.menu` when you want guides and API reference sections side by
side.

```json
{
  "navigation": {
    "menu": {
      "type": "segmented",
      "items": [
        {
          "label": "Guides",
          "pages": ["getting-started/quickstart"]
        },
        {
          "label": "API Reference",
          "openapi": {
            "source": "openapi.json"
          }
        }
      ]
    }
  }
}
```

Each menu item must contain either `pages` or `openapi`.

## Add API reference to tabs

Use `navigation.tabs` when API reference should be a primary section above the
sidebar.

```json
{
  "navigation": {
    "tabs": {
      "presentation": "topbar",
      "items": [
        {
          "label": "Guides",
          "pages": ["getting-started/quickstart"]
        },
        {
          "label": "API Reference",
          "slug": "api",
          "openapi": {
            "source": "openapi.json"
          }
        }
      ]
    }
  }
}
```

Each tab must contain one of `pages`, `menu`, or `openapi`. If
`presentation` is omitted, tabs use `topbar`.

## Add one endpoint page

Use an OpenAPI page item when you want a specific endpoint to appear alongside
other pages in a normal `pages` navigation structure.

```json
{
  "navigation": {
    "pages": [
      "getting-started/quickstart",
      {
        "openapi": {
          "source": "openapi.json",
          "endpoint": "GET /customers"
        },
        "title": "List customers"
      }
    ]
  }
}
```

Radiant validates that the endpoint exists in the source file.

## Link to generated endpoints

Use endpoint links when MDX prose should point to generated OpenAPI endpoint
pages. Link to the endpoint identity, not the generated browser URL.

Use the shorthand form when exactly one rendered OpenAPI source contains the
endpoint:

```mdx
[List customers](<GET /customers>)
```

Markdown link destinations with spaces must be wrapped in angle brackets. The
angle brackets are not part of the rendered link.

If more than one rendered OpenAPI source contains the same method and path, add
the OpenAPI source before the endpoint:

```mdx
[List customers](<api/openapi.yaml#GET /customers>)
```

Use the same source string that appears in `docs.json`. If the source is a
remote URL, use that URL before `#GET /path`.

Component `href` props use the same endpoint target as a quoted string:

```mdx
<Card title="List customers" href="GET /customers">
  Review request and response details.
</Card>
```

Endpoint links are valid only when the endpoint is rendered as a page. This
means validation checks both the OpenAPI source and the `docs.json` navigation
that generates pages.

| Situation | Result |
| --- | --- |
| The endpoint is rendered by one OpenAPI source | Shorthand link works |
| The endpoint is rendered by multiple OpenAPI sources | Use the explicit source form |
| The endpoint exists but is excluded or omitted from `include` | Validation fails |
| The endpoint exists only in an OpenAPI source that is not rendered | Validation fails |
| The endpoint does not exist in the source | Validation fails |

Do not link directly to generated endpoint URLs such as
`/api-reference/customers-get`. Radiant rewrites endpoint links to the correct
generated URL during the build.

## Published OpenAPI output

When Radiant builds API reference pages from a local OpenAPI source, the
published docs site also exposes that spec at its public path, such as
`/openapi.json` or `/api/openapi.json`.

Generated endpoint pages also have Markdown versions. Endpoint Markdown includes
the method, path, parameters, request body, responses, a link to the full spec,
and a compact OpenAPI operation block with the schemas and security schemes
referenced by that endpoint.

## API playground proxy

The API playground can send requests through Radiant's hosted proxy. The proxy
is enabled by default.

Disable it with `playground.proxy`:

```json
{
  "playground": {
    "proxy": false
  }
}
```

When the proxy is enabled, Radiant builds an allowlist from HTTPS server origins
in the OpenAPI `servers` list. Playground requests must target one of those
origins.

<Callout type="tip" title="Keep OpenAPI servers accurate">
If the playground cannot send a request, check that the OpenAPI source includes
the correct HTTPS server URL.
</Callout>

## Write better API reference content

Radiant uses your OpenAPI source to render endpoint pages and prepare assistant
context. Fill in:

- Operation summaries and descriptions.
- Parameter descriptions.
- Request body descriptions and schemas.
- Response descriptions and examples.
- Error responses.
- Authentication details.

The more complete your OpenAPI source is, the more useful the generated API
reference and Knowledge Assistant answers become.

## Common questions

<AccordionGroup>
  <Accordion title="Can I use a remote OpenAPI URL?">
    Yes. The URL must return OpenAPI JSON or YAML. If the URL returns HTML,
    validation fails.
  </Accordion>

  <Accordion title="Can I show only some endpoints?">
    Yes. Use `include` to list the endpoints to show, or `exclude` to hide
    endpoints from a larger generated reference. Do not use both in the same
    OpenAPI object.
  </Accordion>

  <Accordion title="Why did validation fail for an endpoint page?">
    Endpoint page items must use an endpoint that exists in the OpenAPI source,
    written as `METHOD /path`, for example `GET /customers`.
  </Accordion>

  <Accordion title="Does OpenAPI help Knowledge Assistant?">
    Yes. Generated API reference pages give Knowledge Assistant structured context for exact
    methods, paths, parameters, request bodies, responses, and errors.
  </Accordion>
</AccordionGroup>

## Next pages

<Columns columns={3}>
  <Column>

  <Card title="Navigation" href="/configure-with-docs-json/navigation" icon="lucide:list-tree">
    Place API sections.
  </Card>

  </Column>
  <Column>

  <Card title="Write docs for better answers" href="/knowledge-assistant/write-docs-for-better-answers" icon="lucide:file-search">
    Improve AI retrieval.
  </Card>

  </Column>
  <Column>

  <Card title="Use the CLI" href="/getting-started/use-the-cli" icon="lucide:terminal">
    Preview source changes.
  </Card>

  </Column>
</Columns>