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. |
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. |
## 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
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. |
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
--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 |
RQB_ prefix and converted to lower camel case:
| OS variable | Reqbook variable |
|---|
RQB_AUTH_TOKEN | authToken |
RQB_BASE_URL | baseUrl |
RQB_USER_ID | userId |
