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 import command converts existing API definitions into MarkApiDown markdown spec files and drops them into your api-docs/ collection. Every subcommand writes one .md file per endpoint, with correct frontmatter and section structure, ready to validate and run immediately.

​
Overview of mad import

mad import has five subcommands covering the most common API description sources:
SubcommandSource
mad import curlA raw curl command read from a file or stdin
mad import postmanA Postman Collection v2.1 JSON file
mad import insomniaAn Insomnia v4 JSON export
mad import openapiAn OpenAPI 3.x YAML or JSON file
mad import projectYour project’s source code or running dev server
After any import, run mad validate api-docs/ to confirm all generated specs are structurally valid before you start modifying them.

​
Import from cURL

Pass the path to a file containing the curl command, or pipe the command from stdin. MarkApiDown parses the method, URL, headers, and body and writes a spec file into api-docs/.
Save the curl command to a text file, then pass the file path as an argument:
mad import curl curl-command.txt
The import creates a file such as api-docs/apis/users/get-users.md with the method, path, and headers pre-populated. Authorization header values are replaced with {{authToken}} — move the actual value to .env.local or a MAD_* environment variable.

​
Import from Postman

Export your Postman collection as Collection v2.1 JSON (File → Export → Collection v2.1) and run: 
mad import postman my-collection.json
MarkApiDown converts each request in the collection to a spec file. Folder names become resource directory names. Simple status and body assertions are mapped to ## Expected response blocks. JavaScript pre-request scripts and complex test assertions become agent-task blocks for manual review. After the import, scan the generated files for agent-task blocks and decide whether to implement each as a structured ## Assertions rule or remove it.

​
Import from Insomnia

Export your Insomnia workspace as Insomnia v4 JSON (Application → Preferences → Data → Export Data → Current Workspace) and run: 
mad import insomnia insomnia_export.json
Insomnia request groups map to resource directories. Template variables ({{ var }}) are converted to {{var}} syntax. Plugin-based pre/post-request logic is imported as agent-task blocks.

​
Import from OpenAPI

Point mad import openapi at any OpenAPI 3.x file in YAML or JSON format: 
mad import openapi openapi.yaml
mad import openapi openapi.json
Each operation in the spec becomes one endpoint file. The first servers URL becomes the baseUrl in _shared/env.md under the dev environment. Add additional server URLs to env.md manually as extra environment sections.
MarkApiDown imports only the first documented response code per operation. If your OpenAPI spec documents multiple response codes (200, 400, 404), only the first is written to ## Expected response. Document the others in ## Notes or add them as separate spec files.

​
Scan project source code

mad import project scans your project for API route definitions and creates spec files for any routes that do not already have one. It uses a four-priority import strategy:
1

Explicit URL (highest priority)

If you pass --url, MarkApiDown fetches the OpenAPI spec from that URL and imports it directly — no scanning needed.
mad import project --url http://localhost:8000/openapi.json
2

Static OpenAPI file

MarkApiDown searches the project directory for common OpenAPI file names (openapi.yaml, openapi.json, swagger.yaml, etc.). If found, it imports the full spec including parameters, request bodies, and response schemas.
3

Running dev server

If --port is provided, MarkApiDown probes the running server for an OpenAPI spec at common paths (/openapi.json, /docs/openapi.json, /api-docs). Use this when your framework generates an OpenAPI spec at runtime.
mad import project --port 8000
mad import project ./src --port 3000
4

Regex source scan (fallback)

If no OpenAPI spec is found, MarkApiDown falls back to a regex-based scan of your source code. It detects route definitions in Express, FastAPI, Spring Boot, Gin, and other common frameworks and imports the method and path. Request bodies and response schemas are not available from a static scan.
Run mad import project from your project root without any flags to let MarkApiDown choose the best available strategy automatically: 
mad import project
Or specify a subdirectory to scan: 
mad import project ./src
After a source scan, MarkApiDown prints a summary of found routes, created files, and any files that were skipped because a spec already existed.

​
Import via the browser UI

If you have mad-ui open with mad serve, you can also import from cURL without leaving the browser:
  1. Open the New Request panel by clicking New Request in the top navigation bar.
  2. Paste a curl command into the cURL input field.
  3. The panel automatically parses the command and populates the method, URL, headers, and body fields.
  4. Send the request to verify it, then click Save as spec to write it to api-docs/.
This is the fastest path from a DevTools Copy as cURL action to a saved, runnable spec.

​
What gets created

Every import subcommand writes files into api-docs/apis/<resource>/ following the MarkApiDown spec convention. Each file includes:
  • Frontmatter with resource, protocol, method, path, version, and env set correctly.
  • A ## Request section with the resolved HTTP block.
  • A ## Expected response section with the recorded or inferred response, or an empty stub ({}) if no response data was available.
  • An optional ## Tests or ## Notes section for imported comments and agent-task blocks.
Files are never overwritten — if a spec already exists for a given method and path, the import skips it and reports the count of skipped files.

​
After importing

Run mad index after any import to regenerate api-docs/README.md with an up-to-date list of all spec files. The index is used by the browser UI sidebar and by the MCP server.
mad index
Always validate immediately after importing. Run mad validate api-docs/ to catch any structural issues in the generated files before you start editing them. Exit code 2 points to a spec with invalid frontmatter or a missing required section. Exit code 5 means a secret was imported into a versioned file — move it to .env.local right away.