Skip to main content

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.

The mad-ui browser interface gives you a visual workspace over the same markdown files you edit in your code editor. Run mad serve to launch it — every spec, variable, and flow you see in the browser is a plain file on disk, so your agent and your editor stay in sync with the browser automatically.

​
Launch the browser UI

Open a terminal in your project root and run: 
mad serve
The server starts at http://127.0.0.1:8080 by default. Pass flags to change the bind address, port, active environment, or enable mock mode: 
mad serve --port=9000 --env=staging
mad serve --host=0.0.0.0 --port=8080
mad serve --mock
FlagDefaultDescription
--port8080TCP port to listen on
--host127.0.0.1Host to bind — use 0.0.0.0 to share on your local network
--envdevEnvironment loaded from _shared/env.md on startup
--mockoffServe recorded ## Expected response blocks instead of making real HTTP calls
Binding to 0.0.0.0 exposes the local preview to other devices on your network. Use it intentionally — for example, to test a mobile client against a locally served mock — and not as a default.

​
The endpoint list

The home page of mad-ui shows every spec file in api-docs/apis/, organized into resource groups. Use this page to find, filter, and navigate to individual endpoints. Stats bar — A row at the top of the list shows a live count of all specs grouped by their last run result: Total, Passing, Failing, and Not Run. Clicking a group filters the list to matching specs. Search — Press ⌘K (macOS) or Ctrl+K (Windows / Linux) to open the search overlay and find any spec by title, path, method, or tag. Method filter chips — Click a method chip (GET, POST, PUT, PATCH, DELETE) below the search bar to filter the list to specs using that HTTP method. Click again to deselect. Resource groups — Specs are grouped by the resource field in their frontmatter. Each group shows all methods for that resource, making it easy to see the full surface area of an entity without navigating between files.

​
The endpoint detail page

Click any spec in the list to open its detail page. The page has four tabs.
Shows the resolved HTTP request block from the spec — method, URL with variables substituted, headers, and body. This is a read view; use the runner panel to send the request with overrides.

​
The runner panel

The runner panel sits in the right column of the endpoint detail page. It lets you override request inputs for a single execution without touching the spec file.
1

Fill path params

If the spec path contains :param segments (for example, /users/:userId), the runner panel shows a field for each one. Enter a value to substitute it for the run.
2

Add variable overrides

Type a variable name and value to inject it for this run only. Overrides take precedence over env.md values and do not persist between runs.
3

Add extra headers

Click Add header to inject a header that is not in the spec. Useful for adding a one-off X-Debug flag or a session cookie without modifying the spec.
4

Edit the body

For POST, PUT, and PATCH requests, the body editor is pre-populated from the spec. Modify it freely — the spec file is not changed.
5

Run

Click the Run button to send the request. Results appear in the result card below the runner panel.
None of the runner panel inputs are written to the spec file automatically. To make a runtime change permanent, edit the spec in the Source tab or update the file directly in your editor.

​
Reading results

After you click Run, the result card appears below the runner panel with four tabs of its own.
TabWhat it shows
DiffA side-by-side or inline diff of the actual response against the ## Expected response block. Green lines match; red lines diverge.
BodyThe formatted response body — JSON is pretty-printed, plain text is shown as-is.
HeadersAll response headers returned by the server, including status code and duration.
RequestThe exact HTTP request that was sent — resolved URL, headers, and body. Use this to confirm variable substitution happened correctly.

​
cURL preview

Every endpoint detail page has a Copy as cURL button. Click it to copy the resolved request as a curl command you can paste directly into a terminal or share with a teammate. The cURL command reflects the current variable substitution and any runner panel overrides you have set.

​
New Request panel

The New Request panel lets you build and send a one-off HTTP request without creating a spec file first. Click New Request in the top navigation bar or navigate to http://127.0.0.1:8080/request.

Build from scratch

Choose a method, enter a URL, add headers and a body, then click Send. Results appear in the same response viewer used on endpoint detail pages.

Paste cURL

Paste a curl command copied from your browser DevTools or a colleague’s message. The panel parses it automatically and populates the method, URL, headers, and body fields.
After sending a request, you can save it as a spec by entering a relative path in the Save as spec field (for example, apis/users/get-users.md) and clicking Save. The saved file appears in the endpoint list immediately and can be run with mad exec from the CLI. Without a save path, ad-hoc requests are saved to the scratch workspace so you can review them later.

​
Variables drawer

Click Variables in the top navigation bar to open the variables drawer. It has two tabs.
Shows variables stored in your browser’s localStorage — values you have set in the runner panel or the New Request panel during this session. These variables are local to your browser and are not committed to the repo.

​
Environment switcher

The active environment is shown in the top navigation bar. Click it to open a dropdown of all environments defined in _shared/env.md. Switching environments reloads the variable set and updates the resolved URLs across all open spec views. You can also set the environment at launch time with --env=staging so the UI opens directly in a non-default environment.

​
Flow canvas

Click Flows in the top navigation bar to open the flow canvas. This is the visual editor for api-docs/flows/ pipelines. On the canvas you can:
  • Add endpoint nodes by clicking Add step and selecting a spec from your collection.
  • Connect nodes by dragging from one step’s output to the next step’s input.
  • Configure captures — set response.body.id or response.body[0].token as named variables to pass to downstream steps.
  • Set injections — map a captured variable into a path param, header, or body field of a later step.
  • Run the pipeline with the Run flow button to execute all steps in order and see per-step results inline.
  • Save the flow to write the pipeline back to api-docs/flows/<name>.md, making it runnable with mad flow from the CLI.

​
Mock mode

Run mad serve --mock to start the browser UI in mock mode. In mock mode, clicking Run returns the recorded ## Expected response block from the spec instead of making a real HTTP request. 
mad serve --mock
A MOCK badge appears on every response card so you always know you are looking at recorded data rather than a live response. A mock chip also appears in the top navigation bar while mock mode is active. Mock mode is useful when:
  • The backend is not running yet and you want to review API shapes early.
  • You are on an airplane or otherwise offline.
  • You are doing a demo and want stable, predictable responses.
For frontend development that needs a real HTTP server at a separate URL, use mad mock instead — it starts a standalone server on port 4001 that your frontend code can point to directly.