Configuration reference

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

---
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

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.

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.

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.

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.

# 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.

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`

​Project config: api-docs/reqbook.md

​Frontmatter fields

​Complete example

​## Defaults section

​## Web preview section

​## Plugins section

​## Notes section

​Auth modes

​Retry policy

​Environment config: template and local files

​Variable resolution priority

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

Frontmatter fields

Complete example

## Defaults section

## Web preview section

## Plugins section

## Notes section

Auth modes

Retry policy

Environment config: template and local files

Variable resolution priority