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.

MarkApiDown gets you from zero to a running API spec in a single terminal session. You install one binary, initialize a project directory, start the browser UI, execute an endpoint from the CLI, wire up your coding agent, and validate the workspace before your first commit — each step builds directly on the last.
1

Install MarkApiDown

Choose the method that matches your environment. Every option installs the same mad binary; the difference is only how it arrives on your machine.
The recommended path for macOS and Linux. The script fetches the latest prebuilt binary and places it in ~/.local/bin.
curl -fsSL https://markapidown.net/install.sh | sh
If ~/.local/bin is not yet on your PATH, the installer prints the exact export line to add to your shell profile.
Verify the install succeeded:
mad version
# 0.1.0
If mad is not found after installing, open a new terminal tab so your shell reloads the updated PATH.
2

Create a project workspace

Navigate to your project root (or a new directory) and run mad init. The --yes flag accepts every default so the command completes without prompts.
mkdir my-api && cd my-api
mad init --name=my-api --dev-url=https://jsonplaceholder.typicode.com --yes
mad init creates the following structure:
api-docs/
├── README.md
├── mad.md                        # Project config: name, default env
├── _shared/
│   └── env.md                    # Base URLs for dev, staging, prod
├── apis/
│   └── posts/
│       └── get-posts.md          # Sample endpoint — runs immediately
└── flows/                        # Empty; add multi-step pipelines here
.gitignore                        # Pre-configured to exclude .env.local
The generated get-posts.md calls JSONPlaceholder’s public API, so you can run it right away without standing up a local server.
The --dev-url flag sets the base URL for the dev environment in _shared/env.md. You can add --staging-url and --prod-url flags to populate those environments at init time, or edit env.md later.
3

Open the browser UI

Start the local preview server. mad serve reads your api-docs/ directory and renders everything in the browser.
mad serve
# → Preview: http://127.0.0.1:8080
Open http://127.0.0.1:8080 in your browser. From the UI you can:
  • Browse all endpoint files in the left sidebar.
  • Switch between dev, staging, and prod environments with a dropdown.
  • Fill path parameters such as postId in the request builder without editing the markdown.
  • Add runtime-only headers or body overrides that stay temporary (they do not modify the file).
  • Send the request and inspect the formatted response alongside the raw headers.
  • Import an endpoint from a cURL command with the Import button.
  • Open the Flow canvas to build multi-step pipelines visually.
Changes made in the request builder are temporary by default. Switch to Edit mode in the UI and save to write runtime values back into the markdown file.
4

Run the spec from the terminal

Keep the browser UI running and open a second terminal. Execute the same spec with mad exec to see how the CLI surface works — the underlying file is identical.
mad exec api-docs/apis/posts/get-posts.md --env=dev
Expected output:
GET https://jsonplaceholder.typicode.com/posts/1
status:   200
duration: 180ms
Use --dry-run to print the fully resolved request without sending it — useful for verifying variable substitution before hitting a live API:
mad exec api-docs/apis/posts/get-posts.md --env=dev --dry-run

GET https://jsonplaceholder.typicode.com/posts/1
status:   DRY RUN
duration: 0ms
headers:
  accept: application/json
Pass --var key=value to override any variable defined in the spec or environment file at runtime, without editing either file. For example: --var postId=5.
5

Install agent skills

Give your coding agent the knowledge it needs to work with MarkApiDown specs. mad install skills writes skill files and slash-command definitions for every supported agent it detects in your environment.
mad install skills
To target a specific agent instead:
mad install skills --agent=claude-code
mad install skills --agent=cursor
mad install skills --agent=copilot
Once skills are installed, you can delegate API work directly in your agent chat:
Add a MarkApiDown spec for GET /users/:userId and validate it.

Create a flow that fetches a post, captures the userId field, then fetches that user.
The agent writes markdown, runs mad validate, and commits the result — no GUI interaction required.
6

Validate before you commit

Run mad validate against the entire api-docs/ directory to catch structural errors, broken environment references, and malformed specs before they reach your pull request.
mad validate api-docs/
A clean run prints a summary and exits with code 0. Any failure exits non-zero with a file path, line number, and description of the problem.Add this command to your CI pipeline so every pull request is validated automatically:
# .github/workflows/ci.yml (example)
- name: Validate API specs
  run: mad validate api-docs/
mad validate does not send any HTTP requests. It only checks that every spec is structurally valid and that all referenced environment variables are defined. It is safe to run offline and in restricted CI environments.

​
Next steps

Set up agents

Install skills, slash commands, and MCP tools for Claude Code, Cursor, and Copilot — the full integration guide.

Web preview

Learn the browser UI in depth: request tuning, mock mode, cURL import, and the flow canvas.

Vibe coding guide

Patterns for using MarkApiDown as the API layer in your agent coding loop.