---
title: "OpenAPI options"
description: "Every key an api entry and an API version accept, with type, default and what it does, plus the routes a reference publishes."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI options

Each `api` entry in the Nimbus config declares one API reference. To set one up, see [Add an OpenAPI reference](/api-reference/openapi/setup).

## `api` entry

| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `collection` | `string` | — | **Required.** The content collection key, matched by `apiCollection()` in `src/content.config.ts`. |
| `spec` | `string` \| `{ source, path }` \| object | — | The OpenAPI 3.x document: a project-relative path, a file in a [content source](/content-sources/git#api-specs-from-a-source), or an inline object. Omit when `versions` is set. |
| `versions` | `ApiVersion[]` | — | A version family instead of one `spec`. See [API versions](/api-reference/versions). |
| `versionUrl` | `{ in: "path" }` \| `{ in: "query", param? }` | `{ in: "path" }` | Where the version sits in URLs. Query mode needs request rendering. |
| `label` | `string` | `collection` | The API's name in build messages. |
| `requireOperationId` | `boolean` | `false` | Fail the build when an operation has no `operationId`, instead of deriving a coordinate from its method and path. |
| `routes` | `{ convention, stripPathPrefixes?, operations? }` | — | The route convention. See [Routes and coordinates](/api-reference/openapi/routes). |
| `sidebar` | `"full"` \| `"on-demand"` | `"full"` | How much of the navigation each page includes. See [Large APIs](/api-reference/large-apis). |
| `schemaPages` | `boolean` | `false` | Publish a page for every schema, and make schemas citable. |
| `samples` | `{ generate?, keepGenerated? }` | all three languages | Which code samples Nimbus generates. See [Code samples](/api-reference/openapi/code-samples). |
| `extensions` | `string[]` | — | The `x-*` fields to copy onto pages. See [Vendor extensions](/api-reference/openapi/extensions). |
| `publishSpec` | `boolean` | `true` | Publish the spec as JSON and list it in the API catalog. |
| `bundle` | `boolean` | `true` | `false` stores page data as static assets, read on request. Needs request rendering and the Cloudflare or Node adapter. See [Large APIs](/api-reference/large-apis#many-versions). |

## API version

Each item in `versions`:

| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `version` | `string` | — | **Required.** The version id: lowercase letters, digits, dots and dashes, starting and ending with a letter or digit. Part of every non-default URL. |
| `spec` | `string` \| `{ source, path }` \| object | — | **Required.** This version's document. |
| `default` | `boolean` | first version | Serves this version at the family's own path. The default can't be `hidden`. |
| `status` | `"ga"` \| `"beta"` \| `"deprecated"` | — | `deprecated` shows a banner on every page of the version. |
| `hidden` | `boolean` | `false` | Leaves the version out of the picker, search and sitemap. Its pages still load. |
| `label` | `string` | `version` | The version's name in the picker. |
| `routes` | as above | — | This version's route convention. |
| `publishSpec` | `boolean` | the entry's | Overrides the entry's `publishSpec`. |
| `extensions` | `string[]` | the entry's | Replaces the entry's `extensions` list. |

## Published spec

Each collection publishes its spec as one self-contained JSON file at `/api/openapi.json` (`/openapi.json` for a reference at the root), with versions at their own mount path, and lists it in the site's API catalog. Set `publishSpec: false` on a collection, or on a single version, to keep that spec unpublished:

```ts title="astro.config.ts"
api: [
  {
    collection: "api",
    spec: "./src/api/openapi.yaml",
    publishSpec: false,
  },
],
```

## Published outputs

For a collection named `api`, the reference integrates with these routes when their corresponding starter routes are present:

| Route | Purpose |
| --- | --- |
| `/api` | Default-version API overview. |
| `/api/<page-slug>` | Operation, tag, or webhook page, and schema pages with [`schemaPages: true`](/api-reference/openapi/routes#schema-pages). |
| `/api/<page-slug>/index.md` | Clean Markdown version. |
| `/api/llms.txt` | API-only `llms.txt` index. |
| `/llms.txt` and `/llms-full.txt` | Site-wide page index and full Markdown documentation. |
| `/nimbus-api/coordinates.json` | Public coordinate-to-URL manifest. |
| `/api/index/<n>/` | The [API home](/api-reference/large-apis#the-api-home)'s later parts (`noindex`). |
| `/api/openapi.json` | The published spec; other versions at `/api/<version>/openapi.json`. See [Published spec](#published-spec). |
| `/.well-known/api-catalog` and `/.well-known/ard.json` | The site's API catalog and discovery manifest, listing each visible version. |

The API entries also join the existing Pagefind search, sitemap, and OG-image routes when those features are enabled in the project.

Source: https://nimbus-docs.com/api-reference/openapi/options/index.mdx