Reqbook

Reqbook is executable API documentation for humans, CI, and coding agents. Keep API docs, tests, and agent context in one Markdown source of truth.

cargo install reqbook
rqb init --name=my-api --dev-url=http://localhost:8080 --yes
rqb serve                          # opens rqb-ui
rqb request GET https://httpbin.org/get  # ad-hoc request (rqb-cli)

Surfaces

Interface	Launch	Use for
rqb-cli	rqb <command>	Scripts, CI, agents, ad-hoc requests
rqb-ui	rqb serve	Interactive design, debugging, review
Reqbook desktop	cargo run -p rqb-desktop	Native desktop shell around the local web preview
VS Code extension	packages/vscode	In-editor preview, run, validate, context, and variable autocomplete

Why Reqbook

Capability	What it means
Collections	api-docs/ is a collection — auto-located from your git repo root.
Ad-hoc requests	rqb request GET <url> or "New Request" in the browser — no spec file needed.
API design	Write specs in markdown, validate contracts, iterate on design.
Markdown-native	Specs live in reviewable .md files alongside your code.
Local Rust binary	Fast CLI and browser preview without a hosted workspace.
Flow canvas	Connect endpoints, capture values, inject downstream — save as markdown.
Agent-native	Give Claude Code, Cursor, Copilot, and others runnable API contracts they can read, write, and validate.
Contract checks	Run rqb check in CI with Markdown, GitHub, JUnit, or JSON reports.
Import, export, scan	Import cURL/Postman/Insomnia/OpenAPI/local client collections/.http, export OpenAPI, or scan a project for missing specs.

Project layout

api-docs/
├── reqbook.md
├── _shared/
│   ├── env.template.md
│   └── env.md
├── apis/
│   └── users/
│       └── get-user-by-id.md
└── flows/
    └── user-onboarding.md

Quick start

Create a project:

rqb init --name=my-api --dev-url=https://jsonplaceholder.typicode.com --yes

Run an endpoint:

rqb exec api-docs/apis/posts/get-posts.md --env=dev

Open the web preview:

rqb serve

Run the desktop app from source:

cd web && npm ci && npm run build
cd ..
cargo run -p rqb-desktop

Run the flow canvas E2E:

cd web
NPM_CONFIG_UPDATE_NOTIFIER=false npm ci
npm run build
npx playwright install chromium
cd ..
cargo build --locked
cd web
npm run e2e:flow

Install AI agent skills:

rqb skills install --agent=claude-code
rqb skills install --agent=cursor
rqb skills install --agent=copilot

Scan an existing project for routes:

rqb import project .

Installation

Install the rqb CLI with the channel that fits your environment:

# macOS or Linux, prebuilt binary
curl -fsSL https://markapidown.net/install.sh | sh

# npm wrapper around the native binary
npm install -g reqbook

# build from crates.io
cargo install reqbook

# Homebrew tap
brew install reqbook/tap/rqb

Windows MSI installers, Docker images, and checksums are published from the GitHub Releases workflow. See the full install guide at https://docs.markapidown.net/installation.

For local development from source:

git clone https://github.com/ngoclinh93qt/ReqBook.git
cd ReqBook
cargo install --path .

Feedback and anonymous usage

The web and desktop UI include a Feedback and support button for GitHub Discussions, structured bug reports, and repository stars.

Anonymous active-usage reporting is off by default. A user can enable it from the support popup. When enabled, Reqbook sends only a random local identifier, the UI surface (desktop or web), the Reqbook version, and a heartbeat. It does not send workspace paths, endpoint URLs, headers, variables, request bodies, responses, or file contents. Disabling the setting removes the local anonymous identifier.

CLI

rqb init
rqb validate api-docs/
rqb exec api-docs/apis/users/get-user-by-id.md --env=dev --var userId=42
rqb diagnose api-docs/apis/users/get-user-by-id.md --env=dev --output=json
rqb flow api-docs/flows/user-onboarding.md --env=dev
rqb flow api-docs/flows/user-onboarding.md --dry-run --output json
rqb check api-docs/ --changed-from origin/main --report github
rqb context users.create --mode surgical --intent implement --brief --max-fields 12 --include variables,request,response,errors,rules,verify
rqb context flow user-onboarding --mode schema --output json
rqb agent pack flow user-onboarding --mode surgical --brief --out .reqbook/agent-context.md
rqb export openapi api-docs/ --out openapi.generated.yaml
rqb import curl
rqb import collection ./local-client-collection
rqb import http ./requests.http
rqb import project .
rqb skills install
rqb serve
rqb doctor

Documentation

• Getting started
• CLI reference
• Configuration reference
• E2E testing
• Desktop smoke testing
• Spec convention
• Benchmarks
• Contributing
• Security policy

License

Apache-2.0. See LICENSE.