---
title: Generate an API reference
description: Connect an OpenAPI specification and customize the interactive endpoint pages Thally generates.
url: https://pr-6-a9c4e9fe1b6c.thally.app/guides/api-reference-setup
---

# Generate an API reference

Connect an OpenAPI specification and customize the interactive endpoint pages Thally generates.

By the end of this guide, your Thally site will have a browsable page for each
operation in an OpenAPI 3.x document. You need a valid YAML or JSON
specification and a local Thally project.

Connect the OpenAPI specification at SPEC_PATH to this Thally documentation project. You are done when Thally validates the specification, generated endpoint navigation reflects the source accurately, representative operations render correctly, and the project passes its documentation check and production build.

Before editing, read AGENTS.md if present, docs.json, package.json, the existing API guides, and the complete specification. Preserve unrelated navigation and any authored pages already paired with operations. Confirm SPEC_PATH resolves from the project root, parses as OpenAPI 3.x, and does not contain unresolved local references.

Add or update the API Reference tab in docs.json. Use the exact source path. Derive tagsOrder from tags that actually exist, keep deliberate existing ordering when it remains valid, and choose defaultGroup only for genuinely untagged operations. Preserve operation IDs, paths, methods, servers, security schemes, schemas, examples, and descriptions exactly as the source defines them. Do not invent authentication, credentials, base URLs, response bodies, or business meaning. Never place a production secret in docs.json or an example.

Run npx thally check and npm run build. Start the local site and inspect at least one read operation and one write operation when both exist. Verify navigation grouping, path and method, parameters, request body, response schemas, examples, authentication fields, generated cURL, overflow, and dark-mode syntax contrast. Do not send a live request unless the specification points to a safe test server and I explicitly approve it.

Report specification errors separately from Thally configuration errors. Include the exact files changed, commands run, operations inspected, source facts preserved, and anything the API owner must correct. Do not commit, push, deploy, modify the specification itself, or change unrelated framework files unless I ask.

## Adding your spec

Place your OpenAPI 3.x spec file in the project root as `openapi.yaml` (or `openapi.json`). Then configure it in `docs.json`:

```json
{
  "tab": "API Reference",
  "api": {
    "source": "openapi.yaml",
    "tagsOrder": ["Users", "Orders", "Products"],
    "defaultGroup": "General"
  }
}
```

The API Reference tab will auto-generate a page for every operation in your spec.

## Configuration options

| Field | Required | Description |
| --- | --- | --- |
| `source` | Yes | Path to your OpenAPI spec file, relative to the project root. |
| `navigation` | No | Set to `false` when authored MDX pages provide API navigation. Defaults to `true`. |
| `tagsOrder` | No | Controls the order tags appear in the sidebar. Unlisted tags appear after. |
| `defaultGroup` | No | Group name for operations without tags. Defaults to `"Endpoints"`. |
| `webhookGroup` | No | Group name for OpenAPI webhook operations. Defaults to `"Webhooks"`. |
| `overrides` | No | Per-operation customizations (see below). |

## Operation overrides

You can customize how individual operations appear in the sidebar and docs:

```json
{
  "api": {
    "source": "openapi.yaml",
    "overrides": {
      "GET /users": {
        "title": "List users",
        "description": "Fetch all users with pagination.",
        "badge": "Stable"
      },
      "DELETE /users/{id}": {
        "title": "Delete user",
        "badge": "Destructive"
      }
    }
  }
}
```

The key format is `METHOD /path` — matching the `method` and `path` from your OpenAPI spec.

Available override fields:

- **`title`** — custom sidebar and page title
- **`description`** — custom description shown below the title
- **`badge`** — a label displayed next to the operation title
- **`group`** — move the operation to a different sidebar group
- **`slug`** — replace the generated URL segments with a string array
- **`hidden`** — keep the operation out of generated navigation

## Tag ordering

By default, operations are grouped by their OpenAPI `tags`. The `tagsOrder` array controls the sidebar order:

```json
"tagsOrder": ["Authentication", "Users", "Orders"]
```

Tags not listed in `tagsOrder` appear after the listed ones, in the order they first appear in the spec.

## Try It panel

Every API operation page includes a **Try It** button that opens an interactive request panel. It:

- Prefills parameters from the OpenAPI schema
- Sends requests through a server-side proxy to avoid CORS issues
- Displays the response with status code, headers, and body
- Generates a cURL command you can copy

Try It is ready when the specification provides at least one server URL. Add
authentication placeholders only when your API requires them; readers can
enter their own credentials before sending a request.

## Replace the example spec

The template ships with a JSONPlaceholder specification so you can test the
generated pages without credentials. To use your own API:

1. Replace `openapi.yaml` with your spec
2. Update the `tagsOrder` in `docs.json` to match your tags
3. Add any `overrides` you want
4. Run `npm run dev` to see the result

## Verify the generated reference

Confirm the expected tags and operations appear, open at least one endpoint,
and compare its parameters and schemas with the source specification. Then run:

```bash
npx thally check
npm run build
```

## Next steps

- [Configure the API playground](/guides/api-playground)
- [Troubleshoot an API reference](/guides/api-troubleshooting)
- [API settings reference](/guides/docs-json-reference#api-reference)