Endpoint Spec Frontmatter Fields: Complete Reference

Every endpoint spec in MarkApiDown begins with a YAML frontmatter block delimited by --- lines. The frontmatter tells MarkApiDown what HTTP request to build, which environments the spec targets, how to authenticate, and how long to wait before giving up. Everything after the closing --- is the human-readable markdown body that documents the request, response, and test assertions.

Run mad validate api-docs/ before executing specs to catch frontmatter errors — missing required fields, unknown auth values, or malformed retry blocks — without sending any real HTTP requests. Exit code 2 means validation failed; exit code 5 means a possible secret was detected in the file.

Complete example

This example is drawn from the JSONPlaceholder sample project included with MarkApiDown. It shows every frontmatter field together. Required fields are always present; optional fields can be omitted to inherit the project default from mad.md.

---
resource: posts
protocol: http
method: GET
path: /posts/:postId
version: 1
env: [dev]
auth: none
timeout: 5000
retry:
  attempts: 0
  backoff: fixed
tags: [posts, read]
---
# Get post by id

Fetches a single post by its stable numeric identifier.

## Request

\`\`\`http
GET {{baseUrl}}/posts/:postId
Accept: application/json
\`\`\`

## Expected response

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

{
  "id": 1,
  "userId": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit"
}
\`\`\`

## Tests

\`\`\`agent-task
- Verify the response status is 200.
- Verify response.body.id equals postId.
- Verify response.body.userId is a positive integer.
- Verify response.body.title is a non-empty string.
\`\`\`

Required fields

These fields must be present in every endpoint spec. mad validate reports an error for any file that is missing one.

resource

string

required

The resource group this endpoint belongs to. MarkApiDown uses this to organise specs in the web preview sidebar and in the output of mad_search. Use a plural noun that matches the URL resource — users, posts, orders.

resource: posts

protocol

string

required

The transport protocol for this request. Always set to http. MarkApiDown uses this field to select the execution engine and may support additional protocols in future versions.

protocol: http

method

string

required

The HTTP verb for the request. Must be one of the standard methods shown in the table below. Use uppercase.

Method	Typical use
`GET`	Retrieve a resource or collection
`POST`	Create a new resource
`PUT`	Replace a resource entirely
`PATCH`	Apply a partial update
`DELETE`	Remove a resource
`HEAD`	Retrieve headers only (no body)
`OPTIONS`	Discover allowed methods / CORS preflight

method: GET

path

string

required

The URL path for the request, relative to baseUrl. Use :paramName syntax for path parameters. At runtime, MarkApiDown substitutes :paramName with the value of the matching variable from the active environment.

path: /posts/:postId

See Path parameter syntax below for details.

version

integer

required

The spec schema version. Always set to 1. MarkApiDown uses this to detect incompatible spec formats without breaking existing files on schema changes.

version: 1

Optional fields

Omitting any of these fields causes MarkApiDown to fall back to the project-level default defined in mad.md. Set them in a spec only when you need to override the project default for that one endpoint.

env

array

List of environment names this spec is intended to target. Serves as documentation and as a filter — mad_search can use it to find specs valid for a specific environment. If omitted, the spec is considered environment-agnostic.

env: [dev, staging]

auth

string

Authentication scheme to use for this request. Overrides the auth value in the ## Defaults block of mad.md.

Value	Behaviour
`none`	No `Authorization` header added
`bearer`	Injects `Authorization: Bearer {{token}}`
`basic`	Injects `Authorization: Basic <base64(user:pass)>`

auth: bearer

timeout

integer

Maximum number of milliseconds to wait for a response before MarkApiDown aborts the request and reports an error. Overrides timeout in mad.md.

timeout: 10000

retry.attempts

integer

Number of times to retry the request after a failure. Set to 0 to disable retries for this endpoint even if the project default is non-zero. Overrides retry.attempts in mad.md.

retry:
  attempts: 2

retry.backoff

string

The retry spacing strategy for this endpoint. Overrides retry.backoff in mad.md.

Value	Behaviour
`fixed`	Equal wait interval between every retry
`exponential`	Doubles the wait interval after each retry

retry:
  backoff: exponential

Path parameter syntax

Use :paramName in the path field to declare a path parameter. MarkApiDown resolves :paramName against the active environment’s variables at execution time — the same pool that {{variableName}} references draw from.

path: /posts/:postId

Reference the same parameter in the request block using the same syntax:

GET {{baseUrl}}/posts/:postId
Accept: application/json

A variable named postId must exist in _shared/env.md for the active environment, in .env.local, in a MAD_POST_ID OS environment variable, or as a --var postId=1 CLI flag.

Variable syntax in request bodies and headers

Use double-curly-brace syntax — {{variableName}} — anywhere in the request body, headers, or URL to inject a resolved variable value. MarkApiDown replaces every {{...}} token before sending the request.

POST {{baseUrl}}/posts
Content-Type: application/json
Accept: application/json

{
  "title": "My new post",
  "body": "Post content goes here.",
  "userId": {{userId}}
}

Use tags to organise specs for agent-driven search. Running mad_search --tag write returns every spec tagged write, giving an AI agent instant access to all the mutation endpoints in your API. Tag conventions like read, write, admin, webhook, or feature names make the corpus navigable at scale.

Override precedence

When the same setting appears in both a spec’s frontmatter and mad.md, the spec always wins. The full precedence order from lowest to highest:

Project defaults (mad.md)

The ## Defaults block in your project’s mad.md provides the baseline for every endpoint.

Endpoint spec frontmatter

Fields in the spec’s own frontmatter override the project default for that specific endpoint.

CLI flags

Flags like --timeout 15000 passed directly to mad exec or mad flow override both the project default and the spec frontmatter.

Frontmatter quick reference

Field	Type	Required	Default
`resource`	string	✅	—
`protocol`	string	✅	—
`method`	string	✅	—
`path`	string	✅	—
`version`	integer	✅	—
`env`	array	—	(all environments)
`auth`	string	—	project default
`timeout`	integer (ms)	—	project default
`retry.attempts`	integer	—	project default
`retry.backoff`	string	—	project default
`tags`	array	—	`[]`

Documentation Index

​Complete example

​Required fields

​Optional fields

​Path parameter syntax

​Variable syntax in request bodies and headers

​Override precedence

​Frontmatter quick reference

Complete example

Required fields

Optional fields

Path parameter syntax

Variable syntax in request bodies and headers

Override precedence

Frontmatter quick reference