Writing API Documentation in Markdown: A Practical Structure

Good API documentation in Markdown isn't about clever formatting. It's about applying the same four-part structure to every endpoint, so a reader always knows where to look.

Quick answer

A Markdown API doc needs four things per endpoint: an endpoint definition (method, path, one-line description), a parameter table, a request example, and a response example. Follow MDN's API reference convention and you land on the same fixed order every reference doc uses — short description first, then the syntax or parameters, then a runnable example, with anything else (auth notes, rate limits) after that. No docs generator required, no special format. Plain GFM Markdown — headings, tables, and fenced code blocks — covers all of it.

Step-by-step

Step 1 — Write the endpoint definition

Start with the method, the path, and one sentence describing what the endpoint does. State the base URL and the auth requirement here too, so a reader doesn't have to hunt for them three sections later.

## GET /v1/notes/{id}

Returns a single note by ID. Requires a bearer token in the `Authorization` header.

**Base URL:** `https://api.example.com`

Step 2 — Document parameters in a table, not prose

A table beats a bullet list for parameters, plain and simple. A reader can scan a dozen rows in seconds instead of reading every line to find the one they actually need. Give it five columns: name, type, required, description, default.

| Name   | Type   | Required | Description               | Default |
| ------ | ------ | -------- | -------------------------- | ------- |
| `id`   | string | Yes      | The note's unique ID       | —       |
| `raw`  | boolean| No       | Return unrendered Markdown | `false` |

Step 3 — Add a request example with a fenced code block

Open and close the block with three backticks, and drop a language identifier right after the opening fence — bash, json, whatever matches the sample. That identifier is what turns on syntax highlighting. Skip it and the block still renders, just as plain, unhighlighted text.

curl https://api.example.com/v1/notes/8f2c \
  -H "Authorization: Bearer YOUR_TOKEN"

Make the example complete and copy-pasteable: a real header, a placeholder token, a real path. A half-written curl command that a reader has to guess at defeats the whole point of showing one. See inline code vs. a fenced code block for when a one-word parameter name belongs in backticks instead of a full block.

Step 4 — Add a response example, success and one error case

Show the actual JSON a caller gets back, not a description of the shape. Include one success response and at least one common error — a 404 for a missing ID, a 401 for a bad token — so the reader knows what failure looks like too, not just success.

{
  "id": "8f2c",
  "title": "Meeting notes",
  "updated_at": "2026-07-30T14:02:00Z"
}

Common problems and fixes

Showing Markdown syntax inside a code sample

Say the code sample you're documenting is itself Markdown — you're showing a reader what a fenced code block looks like. A plain triple-backtick fence closes the moment it hits the first triple backtick inside your sample, which isn't what you want. Wrap the whole thing in four backticks instead of three. An inner triple-backtick fence can't close a quadruple-backtick block, since CommonMark requires the closing fence to match or exceed the opening one.

Long doc pages getting hard to navigate

A page with a dozen endpoints gets long fast. Once you're past four or five, add a table of contents with anchor links at the top so a reader can jump straight to the endpoint they need instead of scrolling past ten others.

Docs drifting out of sync with the API

The most common failure mode here isn't a formatting mistake — it's a parameter that changed in the code six months ago and never made it into the doc. Keep the doc file in the same repository as the API code, and treat a doc update as part of the same pull request as the code change it describes. Documentation that lives somewhere else, a separate wiki or a different tool, tends to go stale within a release or two.

Frequently Asked Questions

What's the minimum structure an API endpoint doc needs in Markdown?

Four pieces: the endpoint definition, a parameter table, a request example, and a response example. Nothing more is required for a reader to call the endpoint correctly without wading through prose.

Should I use a table or a bullet list for parameters?

A table, every time. It gives you columns for name, type, required or optional, and description, so a reader spots the one parameter they care about instead of reading past ten they don't.

How do I show a Markdown code sample inside another code block without it closing early?

Wrap the outer block in four backticks instead of three. Since a closing fence has to match the opening one's character and be at least as long, an inner triple-backtick fence simply can't close a quadruple-backtick block early.

Do I need a language identifier after the opening backticks?

Yes, any time the block is actual code. json, bash, curl — whatever fits — is what turns on syntax highlighting, and typing it costs you nothing.

Where should API docs live so they don't go stale?

In the same repo as the API code, touched in the same pull request as whatever change it's describing. Once docs live somewhere separate, they tend to drift within a release or two.

Doing this with Carets

Writing API docs in Markdown means living in fenced code blocks, parameter tables, and a lot of back-and-forth between the doc file and the API code. Carets is built for exactly that kind of editing — a native, fast notes and code editor for iPhone, iPad, and Mac, with syntax highlighting for the JSON and curl samples you're documenting. That means a request example reads clearly while you're still writing it, not just after it renders. Multi-endpoint docs stay organized in files, projects, and tags, so a resource with a dozen endpoints doesn't turn into one unwieldy file. And because everything stays plain Markdown, your docs stay portable — no proprietary format standing between you and the repository they belong in.

Get Carets on the App Store for iPhone, iPad, and Mac.