API testing for coding agents

API testing for coding agents breaks down when the agent has to rediscover the API from scratch every time. It scans route files, guesses DTO shapes, rebuilds curl commands, finds auth middleware, runs a noisy shell command, and then tries to remember the result inside a chat transcript.

That loop works once. It does not scale across pull requests, CI, or a team using Claude Code, Cursor, Copilot, Codex, Windsurf, and OpenCode at the same time.

The better pattern is simple: keep the API contract in a Markdown file the agent can read, the developer can review, and the CLI can execute.

The problem is not the agent. It is the missing contract.

Most coding agents are good at source files. They can search them, diff them, update them, and run commands against them. They are much less reliable when the API workflow is hidden across a GUI workspace, old README examples, one-off curl snippets, and implementation details spread across routers, middleware, schemas, and tests.

That creates four common failure modes:

• The agent calls the right endpoint with the wrong payload.
• It tests against the wrong environment or forgets an auth variable.
• It updates implementation code but leaves docs and examples stale.
• It reports “works locally” without leaving a reviewable artifact behind.

Reqbook is built around a different assumption: the API contract should be a normal repo file.

api-docs/
  apis/users/post-create-user.md
  apis/auth/post-login.md
  flows/signup-login-profile.md

The file is readable documentation, executable API test, CI input, and agent context at the same time.

What the agent should read

A useful agent-facing API contract is not a giant OpenAPI dump and not a bare curl command. It needs enough context for a code change:

• What the endpoint is for.
• The exact request shape.
• The expected response shape.
• Variables and auth requirements.
• Assertions that define “success.”
• Notes that explain business rules and downstream dependencies.

Here is the shape we use in Reqbook:

# Create user

Creates the first account owner during SaaS onboarding.

## Request

```http
POST {{baseUrl}}/users
Content-Type: application/json
Accept: application/json

{
  "email": "{{email}}",
  "password": "{{password}}",
  "name": "{{name}}",
  "role": "{{role}}"
}
```

## Expected response

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "{{userId}}",
  "email": "{{email}}",
  "status": "pending_verification"
}
```

## Assertions

- status: 201
- body.id: exists
- body.email: equals "{{email}}"
- body.status: in [pending_verification, active]

This is still normal Markdown. A reviewer can read it in a pull request. A developer can run it from the CLI. A coding agent can search it before touching the route handler.

A practical Claude Code, Cursor, and Copilot workflow

Start with a small API workspace:

rqb init --name=my-api --dev-url=http://localhost:8080 --yes
rqb skills install
rqb serve

Then use the same loop for each API change:

1. Ask the agent to inspect the existing api-docs/ contract before editing code.
2. Let it update the endpoint spec alongside the handler, DTO, or schema.
3. Run rqb validate api-docs/ to catch broken Markdown specs.
4. Run rqb exec or rqb flow against a local server.
5. Commit the code change and the API contract change together.

For example:

rqb exec api-docs/apis/users/post-create-user.md --env dev
rqb flow api-docs/flows/signup-login-profile.md --env dev

The important part is not which agent you use. The important part is that every agent sees the same stable API surface. Claude Code, Cursor, Copilot, and Codex should not each invent a different understanding of POST /users.

Use flows for business behavior, not just endpoints

Single endpoints are useful. Business flows are where the workflow becomes hard to fake.

In the examples/saas-auth-api workspace, the onboarding flow reads like product documentation:

1. Create user
   - Capture: response.body.id as userId
2. Login
   - Inject: email, password, userId
   - Capture: response.body.token as authToken
3. Get profile
   - Inject: authToken, userId, email, role

That gives the agent a safe map:

• which endpoint creates the user,
• where the token comes from,
• which value should be passed to the authenticated request,
• which status codes should fail the task.

This is the difference between “run some API tests” and “verify the onboarding behavior this PR changed.”

Put the API test in the pull request

Postman and other API platforms have good automation stories, and API clients are great for exploration. The gap for coding agents is reviewability. If the contract lives outside the repo, the agent can use it only through another bridge. If a collection export is hard to read, reviewers often skip it.

Markdown changes are different:

 ## Expected response
 {
   "id": "{{userId}}",
   "email": "{{email}}",
-  "status": "pending_verification"
+  "status": "active"
 }

That diff tells a reviewer exactly what API behavior changed. It also tells the agent what to test next.

Run it in CI

API testing for coding agents should not depend on someone remembering to click a runner before deploy. Use validation for every pull request:

- name: Validate API docs
  run: rqb validate api-docs/

When CI can boot the backend, run the specs too:

- name: Run API contracts
  run: rqb flow api-docs/flows/signup-login-profile.md --env ci

This keeps examples from becoming stale. If the response shape changes, the failing contract appears in the same pipeline as the code change.

When this workflow fits

Use Reqbook for API testing with coding agents when:

• an agent is adding or changing backend routes,
• endpoint examples keep drifting from implementation,
• API behavior should be reviewed in pull requests,
• CI needs a lightweight API smoke test,
• your team wants local tooling without a hosted workspace,
• you want a bounded API context file instead of forcing agents to scan the entire codebase.

Use a GUI API client when the main job is manual exploration. Use a dedicated HTTP runner when the main job is terse test execution. Use Reqbook when the contract needs to be readable documentation and executable test at the same time.

To start, install Reqbook from the getting started section, compare the workflow in How it compares, or read the Markdown-first pattern in Markdown API testing that runs.