MarkApiDown: Local-First API Workspace in Markdown

MarkApiDown stores every API operation as a plain markdown file that lives alongside your code. You send ad-hoc requests from the terminal or the browser, design API contracts in a format any editor can open, validate them in CI, and let your coding agent read, write, and run everything — without a hosted workspace, without a proprietary binary format, and without signing up for an account.

Three surfaces, one binary

MarkApiDown ships as a single Rust binary that exposes three surfaces. You choose which one fits the moment: the terminal for scripting and automation, the browser for interactive design and debugging, and agent integration for the growing share of work that your AI coding tools handle on your behalf.

mad-cli

Run mad exec, mad flow, mad validate, and mad request from any shell. Scriptable, CI-friendly, and token-efficient for agents.

mad-ui

Launch mad serve and open a browser UI for the New Request panel, endpoint runner, response inspector, and flow canvas.

Agent integration

Install skills and MCP tools so Claude Code, Cursor, GitHub Copilot, and others can list, read, validate, execute, and author specs without shell parsing.

Project layout

Every MarkApiDown project follows a predictable directory structure rooted at api-docs/. When you run mad init, the tool creates this layout automatically; when your agent scans the project, it finds specs exactly where it expects them.

api-docs/
├── mad.md               # Project config: name, default env, base settings
├── _shared/
│   └── env.md           # Base URLs and environment variables (dev, staging, prod)
├── apis/
│   ├── users/
│   │   ├── get-user-by-id.md
│   │   └── create-user.md
│   └── orders/
│       └── post-orders.md
└── flows/
    └── checkout.md      # Multi-step pipeline: chain requests, capture values

Each file is self-contained: it declares the method, URL template, headers, request body, expected response, and any variable references it needs from _shared/env.md. The same file runs in the CLI, renders in the browser UI, feeds the mock server, and validates in CI — you describe the API once.

The workflow

MarkApiDown fits into the way you already work. You write a spec in markdown, run it immediately from the CLI or browser to confirm it matches the live API, commit the file alongside the code change, and let CI validate the whole api-docs/ tree before merge. Agents participate at every stage.

Write a spec

Create or edit a markdown file in api-docs/apis/. Ask your agent to scaffold it, import it from a cURL command, or write it by hand — the format is plain text.

echo "curl -X GET https://api.example.com/users/42" | mad import curl
# → writes api-docs/apis/users/get-user-by-id.md

Run from CLI or browser

Execute the spec against the dev environment from the terminal, or open mad serve and run it interactively in the browser without leaving your editor workspace.

mad exec api-docs/apis/users/get-user-by-id.md --env=dev --var userId=42

Validate in CI

Add a single command to your pipeline. mad validate parses every spec, resolves environment references, and exits non-zero on the first structural error — before broken specs can reach production.

mad validate api-docs/

Agents read and write specs

Because specs are plain markdown, your agent can create new endpoint files, update request bodies, chain specs into flows, and commit the results as reviewable markdown — no GUI automation required.

Create a MarkApiDown spec for POST /orders and link it into the checkout flow.

Why not Postman, Insomnia, or Bruno?

GUI-based API tools are designed for human interaction. That works well when a person is clicking through a request builder, but it breaks down the moment an AI coding agent needs to participate. MarkApiDown was designed from the start so that files, not app state, are the source of truth.

Agents need file-based tools

GUI tools store state in app databases or proprietary binary formats. Agents cannot read or write them reliably. MarkApiDown specs are plain markdown — any agent can open, edit, validate, and commit them without special tooling.

Everything stays in the repo

Specs live in api-docs/ alongside your source code. Every API change goes through your normal code review. There is no “export to share” step and no drift between the tool and what is actually in the repository.

One source, every surface

The same markdown file runs in the CLI, renders in the browser UI, feeds the mock server, and validates in CI. You describe the API once and every surface stays in sync automatically.

No account, no cloud

MarkApiDown is a single static Rust binary with no runtime dependencies. No signup, no workspace ID, no internet dependency at runtime. It works fully offline and installs in seconds.

Key differentiators at a glance

The table below shows how MarkApiDown changes the cost of common tasks, especially for agents operating inside a coding loop.

Task	Without MarkApiDown	With MarkApiDown
Test one endpoint	Read 3+ source files, construct curl, parse stdout (~500 tokens/call)	`mad exec spec.md` — structured result (~50 tokens/call)
Debug a multi-step flow	Write a temp script, manually chain requests, no trace on failure	`mad flow pipeline.md` — per-step state and captured values
Detect a regression	Only after a bug report	`mad validate` in CI fails before merge
Agent discovers APIs	Scan entire codebase (~10,000–50,000 tokens)	`mad search --tag auth` — compact index, instant result
Share tests with team	”Send me the curl”	Commit markdown, review in PR
Mock a backend	Run a live server or hardcode fixtures	`mad mock` from recorded responses

Next steps

Quickstart

Install MarkApiDown, create a project, and run your first API spec in under five minutes.

Set up agents

Install skills, slash commands, and MCP tools for Claude Code, Cursor, and Copilot.

Web preview

Start mad serve and explore the browser UI: request tuning, mock mode, and the flow canvas.

Documentation Index

​Three surfaces, one binary