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

# Agent API Workflow

> Use Reqbook as the API memory and execution layer for coding agents that need runnable specs, flows, and bounded context.

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

<Note>
  If you only want terminal commands, use the [CLI reference](/reference/cli). If you want to inspect and run specs visually, use the [Web preview](/guides/web-preview). This guide focuses on agent-first development.
</Note>

***

## Set up the project

<Steps>
  <Step title="Initialise Reqbook">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Install agent skills">
    ```bash theme={null}
    rqb skills install
    ```

    Or target one agent:

    ```bash theme={null}
    rqb skills install --agent=claude-code
    rqb skills install --agent=cursor
    rqb skills install --agent=copilot
    ```
  </Step>

  <Step title="Register MCP for your agent">
    MCP mode gives the agent structured Reqbook tools instead of asking it to parse terminal output.

    ```bash theme={null}
    rqb install mcp --agent=claude-code
    rqb install mcp --agent=codex-cli
    ```
  </Step>

  <Step title="Open the UI beside your agent">
    ```bash theme={null}
    rqb serve
    ```

    Keep the browser preview open while your agent edits files. The UI reads the same markdown files and updates as they change.
  </Step>
</Steps>

***

## Prompts that work well

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

<CardGroup cols={2}>
  <Card title="Create one endpoint" icon="file-pen">
    ```text theme={null}
    Add a Reqbook spec for GET /users/:userId. Use bearer auth and make userId a path param.
    ```
  </Card>

  <Card title="Scan existing routes" icon="magnifying-glass">
    ```text theme={null}
    Scan this project for API routes and add missing Reqbook specs. Do not overwrite existing specs.
    ```
  </Card>

  <Card title="Run and debug" icon="play">
    ```text theme={null}
    Test the get user endpoint in dev. If variables are missing, tell me exactly where to define them.
    ```
  </Card>

  <Card title="Create a workflow" icon="diagram-project">
    ```text theme={null}
    Build a signup flow: create user, login, capture token, then fetch profile with the captured token.
    ```
  </Card>
</CardGroup>

***

## Agent responsibilities

When the skills are installed, the agent should follow this pattern:

| Task                       | Reqbook surface         | Expected behavior                                                                                   |
| -------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| Add an endpoint            | `rqb_author` MCP tool   | Create `api-docs/apis/<resource>/<method>-<slug>.md`, validate it, regenerate the index.            |
| Run one endpoint           | `rqb_exec` MCP tool     | Resolve env variables, path params, and runtime vars; report status, duration, and diff.            |
| Diagnose a failed endpoint | `rqb_diagnose` MCP tool | Return likely cause, next action, inspect targets, and verify commands before broad source reading. |
| Create a workflow          | `/rqb flow` command     | Save a markdown flow under `api-docs/flows/`.                                                       |
| Run a workflow             | `rqb_flow` MCP tool     | Execute steps, capture values, inject them downstream, and report the first failure.                |
| Review in browser          | `rqb serve`             | Use 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

```text theme={null}
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.
```

<Tip>
  Keep `rqb serve` open during this loop. It gives you a visual review layer while the agent edits markdown behind the scenes.
</Tip>