Markdown Endpoint Files

What is an endpoint file?

An endpoint file is a .md file that serves as both documentation and an executable HTTP request. The CLI, web preview, CI, and AI agents all read the same file there is no separate schema, generated client, or runtime artifact.

Browser UI

The web preview renders the file, lets you run it, and provides runtime-only params, headers, and body overrides.

Coding agents

Agent skills use this structure to create specs safely and validate them before reporting back.

Terminal and CI

rqb exec and rqb validate read the same markdown file for automation.

File location and naming

Endpoint files live under api-docs/apis/<resource>/. The recommended filename format is <method-lower>-<slug>.md.

HTTP method + path	Filename
`GET /users/:id`	`get-user-by-id.md`
`POST /orders`	`post-orders.md`
`DELETE /subscriptions/:id`	`delete-subscription-by-id.md`
`PATCH /orders/:orderId/items/:itemId`	`patch-order-by-order-id-item-by-item-id.md`

Frontmatter reference

Every endpoint file must begin with YAML frontmatter delimited by ---.

---
resource: users
protocol: http
method: GET
path: /users/:id
tags: [users, read]
version: 1
env: [dev, staging, prod]
auth: bearer
timeout: 5000
retry:
 attempts: 0
 backoff: fixed
---

Field	Required	Type	Description	Default
`resource`	yes	string	Resource group and folder name
`protocol`	yes	enum	`http`, `ws`, or `sse`. Only `http` executes in the current release
`method`	yes	enum	`GET` `POST` `PUT` `PATCH` `DELETE` `HEAD` `OPTIONS`
`path`	yes	string	Path with `:param` for path params
`tags`	no	string[]	Searchable labels shown in web preview and reports	`[]`
`version`	yes	integer	Spec version (must be `1`)
`env`	no	string[]	Environments where this endpoint is valid. Empty = all	`[]`
`auth`	no	enum	`none` / `bearer` / `basic` / `custom`	project default
`timeout`	no	integer (ms)	Per-request timeout in milliseconds	`5000`
`retry.attempts`	no	integer	Retry count after failure	`0`
`retry.backoff`	no	enum	`fixed` or `exponential`	`fixed`
`response.match`	no	enum	`shape`, `strict`, or `schema` comparison mode	`shape`
`response.ignore`	no	string[]	Strict-mode paths to ignore, such as `body.id`	`[]`

Unknown frontmatter keys produce a warning and are ignored. This forward-compatible behavior means future Reqbook versions can introduce new fields without breaking existing spec files.

The Request block

## Request must contain exactly one http fenced code block. The first line is the request line; subsequent lines are headers; a blank line separates headers from the optional body.

Request line forms

GET {{baseUrl}}/users/:id
GET /users/:id
POST https://api.example.com/users

Relative URLs are resolved against the selected environment’s baseUrl from api-docs/_shared/env.md. Absolute URLs are used as-is.

Full request with headers and body

POST {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Content-Type: application/json
Accept: application/json

{
 "email": "{{email}}",
 "name": "{{name}}"
}

The Expected response block

## Expected response must contain exactly one http fenced code block. Reqbook diffs the actual response against this block after every execution.

Comparison behavior

Part	Comparison
Status	Strict equality
Headers	Subset match listed headers must be present; extra response headers are allowed
Body	JSON shape when both sides are valid JSON; exact string match otherwise

Set response.match: strict when the JSON/string body must match exactly:

response:
  match: strict
  ignore: [body.id, headers.x-request-id]

Set response.match: schema when the actual JSON body should validate against a schema:

## Schema

```json
{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string" },
    "email": { "type": "string" }
  }
}
```

Example

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

{
 "id": "usr_123",
 "email": "[email protected]"
}

Error responses (optional)

Use ## Error responses to document representative error contracts such as validation failures, missing auth, not found, or conflict cases.

## Error responses

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
 "error": "not_found",
 "message": "User not found"
}
```

the current Reqbook release executes only the single ## Expected response block. Error responses are reference examples for humans, the web preview source view, and AI agents.

The Assertions block (optional)

## Assertions contains structured rules that Reqbook evaluates after each execution. Results appear in rqb_exec output as assertion_results.

## Assertions
- status: 201
- body.id: exists
- body.email: equals "[email protected]"
- body.role: in [admin, user]
- headers.content-type: contains application/json
- body.slug: matches ^[a-z-]+$

Supported operators:

Operator	Example	Description
`exists`	`body.id: exists`	Field is present and non-null
`equals`	`status: 201` or `body.name: equals "Ada"`	Exact match
`contains`	`headers.content-type: contains json`	Substring match
`in`	`body.role: in [admin, user]`	Value is one of a list
`matches`	`body.slug: matches ^[a-z-]+$`	Regex match

Paths follow the format status, body.<field>.<nested>, or headers.<name>.

The Tests block (optional)

## Tests contains an agent-task fenced code block with freeform validation instructions for AI agents. Use this for edge cases that can’t be expressed as structured assertions.

## Tests

```agent-task
- Verify duplicate email returns 409.
- Verify the response time is under 200ms under normal load.
```

Reqbook does not execute agent-task code. The block is read by AI agents as instructions.

Notes section (optional)

## Notes is free-form markdown for team context: rate limits, edge cases, links to related endpoints, and migration notes. The Reqbook parser ignores this section entirely.

Complete example

---
resource: users
protocol: http
method: GET
path: /users/:id
tags: [users, read]
version: 1
env: [dev, staging]
auth: bearer
timeout: 5000
retry:
 attempts: 0
 backoff: fixed
---

# Get user by id

Fetch a single user record by stable user identifier.

## Request

```http
GET {{baseUrl}}/users/:id
Authorization: Bearer {{authToken}}
Accept: application/json
```

## Expected response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
 "id": "usr_123",
 "name": "Ada Lovelace",
 "email": "[email protected]"
}
```

## Tests

```agent-task
- Verify the response status is 200.
- Verify response.body.id equals the requested id.
- Verify response.body.email is a valid email address.
- Verify Authorization header is masked in all output.
```

## Notes

Use this endpoint after login to fetch the current user's profile.

Running an endpoint

Use the UI while developing and the CLI when you need automation.

Web UI
CLI

rqb serve

Open the endpoint, fill runtime-only params or headers, click Run, and inspect the response panel. The markdown file changes only when you enter edit mode and save.

# Basic execution
rqb exec api-docs/apis/users/get-user-by-id.md

# With environment and variable override
rqb exec api-docs/apis/users/get-user-by-id.md --env=staging --var id=usr_456

# Dry run print the resolved request without sending
rqb exec api-docs/apis/users/get-user-by-id.md --dry-run

​What is an endpoint file?

Browser UI

Coding agents

Terminal and CI

​File location and naming

​Frontmatter reference

​The Request block

​Request line forms

​Full request with headers and body

​The Expected response block

​Comparison behavior

​Example

​Error responses (optional)

​The Assertions block (optional)

​The Tests block (optional)

​Notes section (optional)

​Complete example

​Running an endpoint

What is an endpoint file?

File location and naming

Frontmatter reference

The Request block

Request line forms

Full request with headers and body

The Expected response block

Comparison behavior

Example

Error responses (optional)

The Assertions block (optional)

The Tests block (optional)

Notes section (optional)

Complete example

Running an endpoint