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

# Configuration reference

> Project config (reqbook.md), environment config (env.md), auth modes, retry policy, and the web preview settings.

## Project config: `api-docs/reqbook.md`

`api-docs/reqbook.md` is the project configuration file. It uses YAML frontmatter and structured YAML code blocks inside named markdown sections.

### Frontmatter fields

| Field | Required | Type | Description |
| - | - | - | - |
| `name` | yes | string | Project name shown in the CLI, web preview, reports, and generated index. |
| `version` | yes | integer | Reqbook spec format version. Must be `1` for the current spec format. |
| `default-env` | yes | string | Environment used when a command is run without `--env`. |

Unknown frontmatter keys produce a warning and are ignored, allowing future versions to add fields without breaking older clients.

### Complete example

```yaml filename="api-docs/reqbook.md" theme={null}
---
name: my-api
version: 1
default-env: dev
---

# My API

One-paragraph description of the project.

## Defaults

timeout: 5000
retry:
 attempts: 3
 backoff: exponential
auth: bearer

## Web preview

port: 8080
host: 127.0.0.1
theme: auto
autosave: 2s

## Plugins

plugins: []

## Notes

Free-form team notes and conventions. The parser ignores this section entirely.
```

### ## Defaults section

The `## Defaults` code block sets project-wide defaults for every endpoint. Individual endpoint frontmatter can override each value. CLI flags (`--timeout`) override both.

| Key | Type | Built-in default | Description |
| - | - | - | - |
| `timeout` | integer (ms) | `5000` | Request timeout in milliseconds. |
| `retry.attempts` | integer | `0` | Number of retry attempts after the first failure. `0` means no retry. |
| `retry.backoff` | enum | `fixed` | Backoff strategy: `fixed` or `exponential`. |
| `auth` | enum | `none` | Default auth mode: `none`, `bearer`, `basic`, or `custom`. |

If `## Defaults` is absent, the built-in defaults are used for every endpoint.

### ## Web preview section

The `## Web preview` code block controls `rqb serve`. CLI flags (`--port`, `--host`) override these values.

| Key | Type | Default | Description |
| - | - | - | - |
| `port` | integer | `8080` | TCP port for the preview server. |
| `host` | string | `127.0.0.1` | Host to bind to. |
| `theme` | string | `auto` | Color theme: `auto`, `light`, or `dark`. |
| `autosave` | string | `2s` | Debounce interval for live-reload after file changes. |

### ## Plugins section

```yaml theme={null}
plugins: []
```

the current Reqbook release does not execute plugins. The `## Plugins` section is reserved for future use. Keep it as an empty list or omit the section entirely.

### ## Notes section

Free-form prose, checklists, or team conventions. The Reqbook parser ignores this section entirely. Use it for anything that should live alongside the config but not affect execution.

***

## Auth modes

Set the auth mode in `reqbook.md`'s `## Defaults` section (project-wide) or in individual endpoint frontmatter (per-endpoint override).

| Mode | Description |
| - | - |
| `none` | No `Authorization` header added. This is the built-in default. |
| `bearer` | Adds `Authorization: Bearer {{authToken}}`. Requires `authToken` to be resolved from any variable source. |
| `basic` | Adds `Authorization: Basic <base64(username:password)>`. Requires both `username` and `password` variables. |
| `custom` | The request block must include the `Authorization` header explicitly. Reqbook does not inject anything. |

> [!TIP]
>
> Set a project-wide default in `reqbook.md`'s `## Defaults` block, then override per-endpoint with `auth:` in the endpoint's frontmatter. The endpoint value always wins.

***

## Retry policy

Configure retries in `reqbook.md`'s `## Defaults` section or in individual endpoint frontmatter.

```yaml theme={null}
retry:
 attempts: 3
 backoff: exponential
```

| Key | Type | Default | Description |
| - | - | - | - |
| `attempts` | integer | `0` | Number of retry attempts after the first failure. `0` means no retry. |
| `backoff` | enum | `fixed` | `fixed`: retry immediately with no added delay. `exponential`: double the wait between each attempt. |

> [!NOTE]
>
> Retries apply to network errors (exit code `4`) and to `5xx` responses. They do **not** retry on test assertion failures (exit code `1`) or spec errors (exit code `2`). The `--timeout` CLI flag sets the per-attempt timeout.

***

## Environment config: template and local files

Reqbook uses two environment markdown files:

| File | Git behavior | Purpose |
| - | - | - |
| `api-docs/_shared/env.template.md` | Commit | Shared shape and safe defaults for new contributors. |
| `api-docs/_shared/env.md` | Ignore | Local values used by the CLI, web preview, MCP tools, and agents. |

Both files use the same format. Each environment is a second-level heading followed by a `yaml` code block.

```yaml filename="api-docs/_shared/env.template.md" theme={null}
# Environments

## dev

baseUrl: http://localhost:8080
userId: 123
pageSize: 20

## staging

baseUrl: https://staging.example.com
userId: 456

## prod

baseUrl: https://api.example.com
```

The environment name passed to `--env` must match one of these headings exactly. If the heading is missing, Reqbook exits with code `2`.

> [!WARNING]
>
> Do not put secrets in either env markdown file. Tokens, passwords, and private keys must go in `.env.local` or `RQB_*` environment variables. The parser enforces this at validation time and exits with code `5` if a secret pattern is detected.

***

## Variable resolution priority

When the same variable name is defined in more than one source, the highest-priority source wins.

| Priority | Source | Example |
| - | - | - |
| 1 (highest) | Pipeline step capture | `Capture: response.body.id as userId` |
| 2 | CLI `--var` flag | `--var userId=42` |
| 3 | Endpoint frontmatter | `userId: 42` in the endpoint's YAML block |
| 4 | `_shared/env.md` for the selected env | `## dev` block with `userId: 123` |
| 5 | `.env.local` | `authToken=local-dev-token` |
| 6 (lowest) | OS environment variables (`RQB_*`) | `RQB_USER_ID=99` |

OS environment variables are stripped of the `RQB_` prefix and converted to lower camel case:

| OS variable | Reqbook variable |
| - | - |
| `RQB_AUTH_TOKEN` | `authToken` |
| `RQB_BASE_URL` | `baseUrl` |
| `RQB_USER_ID` | `userId` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.