> For a complete documentation index, see /llms.txt. To read any public page as Markdown, append .md to the URL.

CamelMind can generate a fully interactive API reference from an OpenAPI 3.x specification. Once enabled, your API reference is automatically added to the top navigation and stays in sync with your documentation.

Features include:

- Interactive endpoint documentation
- Built-in request and response examples
- Multi-language code samples
- Support for multiple OpenAPI specifications
- Role-based access control
- Version-specific API references

---

<Callout type="important" title="Before you begin">

You'll need an OpenAPI 3.x specification in either YAML or JSON format.

For example:

```text
openapi/
└── openapi.yaml
```
</Callout>

## Enable the interactive OpenAPI reference

To enable the interactive API reference in CamelMind:

1. Configure your OpenAPI specifications in `camelmind.config.ts`.
2. Associate an API specification with each documentation version in `versions.yml`.

<Steps>
  <Step n={1} title="Configure your API specifications">
    Open `camelmind.config.ts` and enable the API Reference.

```ts
const config: CamelMindConfig = {
  apiReference: {
    enabled: true,

    navLabel: "API Reference",

    specs: {
      main: {
        label: "REST API",
        file: "openapi/openapi.yaml",
      },
    },
  },
}
```

This registers the available OpenAPI specifications for your documentation site.
  </Step>
  <Step n={2} title="Associate a spec with a documentation version">
    Open `versions.yml` and specify which API specification should be displayed for each version.

```yaml
versions:
  - id: "latest"
    label: "Latest"
    stable: true
    nav: nav/nav.yml

    api_reference:
      spec: main
```
  </Step>
</Steps>

---

## Add multiple API specifications

If your documentation includes multiple APIs—for example, a public API and a partner API—you can publish multiple OpenAPI specifications as tabs within the same API Reference.

First, register each spec in `camelmind.config.ts`:

```ts
apiReference: {
  enabled: true,

  navLabel: "API Reference",

  specs: {
    main: {
      label: "REST API",
      file: "openapi/openapi.yaml",
    },
    partner: {
      label: "Partner API",
      file: "openapi/openapi-partner.yaml",
    },
  },
},
```

Then configure the tabs for each documentation version in `versions.yml`:

```yaml
versions:
  - id: "latest"
    label: "Latest"
    stable: true
    nav: nav/nav.yml

    api_reference:
      tabs:
        - id: main
          spec: main

        - id: partner
          spec: partner
```

Each tab's `spec` value must match one of the specification IDs defined in `apiReference.specs`.

When users open the API Reference, they can switch between the available API specifications using the tabs at the top of the page.

<Callout type="note" title="See it in action">
This documentation site registers two OpenAPI specifications—`main` and `partner`—and publishes them as tabs in the same API Reference page: [REST API](/api-reference/main) and [Partner API](/api-reference/partner).
</Callout>

---

## Customize API reference code sample languages

To specify which programming languages appear in the generated API reference code samples, configure the `languages` array in `camelmind.config.ts`:

```ts
apiReference: {
  languages: [
    "curl",
    "javascript",
    "python",
  ],
}
```

By default, CamelMind displays code samples for:

- curl
- JavaScript
- Python

---

## Restrict API reference access with user roles

To restrict access to the API reference, specify the required user roles in `camelmind.config.ts`:

```ts
apiReference: {
  roles: [
    "developer",
    "admin",
  ],
}
```

When you leave `roles` empty (`[]`), CamelMind allows public access to the entire API reference.

<Callout type="note">
Role restrictions apply to the entire API reference. You cannot currently restrict individual endpoints independently.
</Callout>

---

## Use different API specs for each documentation version

If your documentation uses versioning, each version can display its own OpenAPI specification.

First, register each version's spec in `camelmind.config.ts`:

```ts
apiReference: {
  enabled: true,

  specs: {
    v2: {
      label: "API v2",
      file: "openapi/v2.yaml",
    },
    v1: {
      label: "API v1",
      file: "openapi/v1.yaml",
    },
  },
},
```

Then reference the matching spec ID for each version in `versions.yml`:

```yaml
versions:
  - id: v2
    label: v2 (Latest)
    stable: true
    nav: nav/nav-v2.yml

    api_reference:
      spec: v2

  - id: v1
    label: v1
    nav: nav/nav-v1.yml

    api_reference:
      spec: v1
```

When users switch documentation versions, CamelMind automatically loads the corresponding API specification.

---

## API reference configuration options

Use these configuration options in `camelmind.config.ts` to customize your API reference settings:

| Field | Description |
|------|-------------|
| `enabled` | Enables the API Reference. |
| `navLabel` | Text displayed in the top navigation. Default: `API Reference`. |
| `specs` | One or more OpenAPI specifications to publish. |
| `languages` | Languages shown for generated code samples. |
| `roles` | Roles required to access the API Reference. Empty (`[]`) makes it public. |

---

## Supported OpenAPI specification formats

CamelMind supports **OpenAPI 3.x** specifications in both YAML and JSON formats.

Example OpenAPI 3.1 specification:

```yaml
openapi: "3.1.0"

info:
  title: My API
  version: "1.0.0"

paths:
  /users:
    get:
      summary: List users
```

<Callout type="note">
The offline package includes the fully rendered API Reference for the downloaded documentation version. Any API references that are accessible on the live site are included in the offline package, allowing you to browse endpoints, request and response schemas, and code samples without signing in or connecting to the internet.
</Callout>