OpenAPI options

Each api entry in the Nimbus config declares one API reference. To set one up, see Add an OpenAPI reference.

`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, or an inline object. Omit when `versions` is set.
`versions`	`ApiVersion[]`	—	A version family instead of one `spec`. See API 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.
`sidebar`	`"full"` \| `"on-demand"`	`"full"`	How much of the navigation each page includes. See 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.
`extensions`	`string[]`	—	The `x-*` fields to copy onto pages. See Vendor 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 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:

astro.config.tsts

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/<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’s later parts (`noindex`).
`/api/openapi.json`	The published spec; other versions at `/api/<version>/openapi.json`. See 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.