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 MarkApiDown mock server reads the ## Expected response blocks in your spec files and serves them over HTTP — no live backend required. Point your frontend application, mobile client, or integration test suite at the mock server and develop against stable, spec-controlled responses.

​
What the mock server does

Every spec file in api-docs/apis/ contains an ## Expected response section that records what the API should return. mad mock reads those blocks and serves them as real HTTP responses on a local port. Requests to the mock server are matched by HTTP method and path — path parameters such as /users/:id are matched loosely, so any value for :id returns the same recorded response body. The mock server does not make any outbound HTTP requests. It only reads from your spec files.

​
Start the mock server

Run mad mock from your project root: 
mad mock
By default, the server listens on port 4001 and reads specs from the api-docs/ directory in the current working tree. 
Mock server running at http://127.0.0.1:4001
Reading specs from: api-docs/
Point your frontend’s API base URL at http://localhost:4001 and all requests are served from the recorded expected responses.

​
Options

FlagDefaultDescription
--port4001TCP port to listen on
--latencynoneArtificial response delay in milliseconds added to every response
[dir]api-docsPath to the api-docs/ root directory containing spec files
# Custom port
mad mock --port=5000

# With latency simulation
mad mock --latency=300

# Explicit api-docs path
mad mock /path/to/other-project/api-docs

# All options together
mad mock --port=5000 --latency=200 /path/to/api-docs
Use --latency to simulate slow network conditions such as a mobile device on a 3G connection or a geographically distant API server. Setting --latency=1000 adds a one-second delay to every response, which helps you discover loading states, timeout handling, and user experience issues before they appear in production.

​
Mock mode in the browser UI

Start the browser UI in mock mode with the --mock flag: 
mad serve --mock
In mock mode, clicking Run in the browser returns the ## Expected response block from the spec instead of making a real HTTP request. A MOCK badge appears on every response card and a mock chip appears in the top navigation bar so you always know you are looking at recorded data. Mock mode in the browser uses the same ## Expected response blocks as mad mock, so the two share the same source of truth — your spec files.

​
Browser mock mode vs standalone mock server

mad serve --mockmad mock
Use caseInteractive review and debugging in the browserFrontend app or integration tests point to a mock HTTP URL
Backend trafficNoneNone
PortSame as the browser UI (default 8080)Separate port (default 4001)
Latency simulationNoYes (--latency)
Requires browserYesNo
Use mad serve --mock when you are actively reviewing specs in the browser. Use mad mock when your application code needs a real HTTP server to talk to.

​
When to use the mock server

Frontend development

Start the mock server alongside your frontend dev server. Your UI code can call real fetch requests against http://localhost:4001 without a backend running.

CI without external services

Run integration tests in CI against the mock server. No staging credentials, VPN, or live service dependency needed — tests are fast and deterministic.

Demos and presentations

Use the mock server to demo an API integration before the backend is built. Responses are stable, predictable, and safe to show publicly.

Offline development

Work on API integrations without internet access. The mock server runs entirely from local spec files.

​
How responses are served

When a request arrives at the mock server:
  1. MarkApiDown matches the request method and path against all spec files in api-docs/apis/.
  2. For the matching spec, it reads the ## Expected response section.
  3. It parses the HTTP status line, headers, and body from that block.
  4. It returns those values as a real HTTP response, with any configured --latency delay added.
If no spec matches the request, the mock server returns a 404 with a JSON body describing the unmatched route. If a spec has an empty ## Expected response block (a stub {}), the mock server returns 200 OK with an empty JSON object. Fill in the expected response block with realistic field names and values to get useful mock responses.

​
How to populate expected responses

The fastest way to populate ## Expected response blocks is to run mad exec against a live server once and copy the response body into the spec manually: 
mad exec api-docs/apis/users/get-user-by-id.md --env=dev --var userId=usr_123
The console output shows the full response. Copy the status, headers, and body into the ## Expected response section of the spec file, then commit it. From that point on, the mock server and mad serve --mock both return that recorded response.
Use mock mode with flow pipelines to test multi-step flows without a live API. Run mad serve --mock and use the flow canvas to verify that capture and inject logic works correctly using recorded responses before you test against a real backend. This catches data-wiring mistakes — missing captures, wrong JSONPath expressions — before they produce confusing live errors.