Skip to main content

​
Make your coding agent API-aware.

Reqbook is strongest when a coding agent is part of your API workflow. The agent can read source routes, create markdown specs, validate them, run requests, and build flows. You still keep control because every result is saved as reviewable markdown in the repo.
If you only want terminal commands, use the CLI reference. If you want to inspect and run specs visually, use the Web preview. This guide focuses on agent-first development.

​
Set up the project

1

Initialise Reqbook

rqb init --name=my-api --dev-url=http://localhost:8080 --yes
This creates api-docs/, an example endpoint, _shared/env.template.md, local _shared/env.md, and .gitignore protection for .env.local plus local _shared/env.md.
2

Install agent skills

rqb skills install
Or target one agent:
rqb skills install --agent=claude-code
rqb skills install --agent=cursor
rqb skills install --agent=copilot
3

Register MCP for your agent

MCP mode gives the agent structured Reqbook tools instead of asking it to parse terminal output.
rqb install mcp --agent=claude-code
rqb install mcp --agent=codex-cli
4

Open the UI beside your agent

rqb serve
Keep the browser preview open while your agent edits files. The UI reads the same markdown files and updates as they change.

​
Prompts that work well

Use prompts that describe the API intent and let the Reqbook skill choose the correct operation.

Create one endpoint

Add a Reqbook spec for GET /users/:userId. Use bearer auth and make userId a path param.

Scan existing routes

Scan this project for API routes and add missing Reqbook specs. Do not overwrite existing specs.

Run and debug

Test the get user endpoint in dev. If variables are missing, tell me exactly where to define them.

Create a workflow

Build a signup flow: create user, login, capture token, then fetch profile with the captured token.

​
Agent responsibilities

When the skills are installed, the agent should follow this pattern:
TaskReqbook surfaceExpected behavior
Add an endpointrqb_author MCP toolCreate api-docs/apis/<resource>/<method>-<slug>.md, validate it, regenerate the index.
Run one endpointrqb_exec MCP toolResolve env variables, path params, and runtime vars; report status, duration, and diff.
Diagnose a failed endpointrqb_diagnose MCP toolReturn likely cause, next action, inspect targets, and verify commands before broad source reading.
Create a workflow/rqb flow commandSave a markdown flow under api-docs/flows/.
Run a workflowrqb_flow MCP toolExecute steps, capture values, inject them downstream, and report the first failure.
Review in browserrqb serveUse the UI for request tweaks, response inspection, and visual flow editing.

​
What stays under your control

  • Agents should not overwrite existing specs unless you explicitly ask for that exact file to be replaced.
  • Secrets belong in .env.local or RQB_*, not in markdown committed to the repo.
  • The browser request builder can override params, headers, and body for one run without changing the markdown file.
  • Persistent changes happen only when the agent edits markdown or you use the UI edit mode and save.
  • rqb validate api-docs/ is the final safety check before commit.

​
Example session

You: Scan this repo and add missing API specs.

Agent: Uses Reqbook project scanner.
Agent: Creates api-docs/apis/orders/post-orders.md.
Agent: Runs rqb validate api-docs/.
Agent: Runs rqb index.

You: Create a checkout flow from the order endpoints.

Agent: Reads existing specs.
Agent: Creates api-docs/flows/checkout.md.
Agent: Captures response.body.id as orderId.
Agent: Validates the flow.

You: Run it in dev.

Agent: Runs rqb flow api-docs/flows/checkout.md --env=dev.
Agent: Reports each step, captured values, and the first mismatch.
Keep rqb serve open during this loop. It gives you a visual review layer while the agent edits markdown behind the scenes.