How to Write API Documentation in Markdown

API documentation tells developers how to use your API. Markdown is the most common format for writing it because the docs live alongside code, work with version control, and render on GitHub, documentation sites, and publishing tools.

This guide covers how to structure API docs in markdown, with templates you can copy and adapt.

Structure of Good API Docs

A complete API documentation set includes these sections:

Documenting an Endpoint

Each endpoint needs these elements:

## Create a Document

Creates a new published document from markdown content.

**Endpoint:** `POST /api/documents`

**Authentication:** Bearer token required

### Request Headers

| Header | Value | Required |
|--------|-------|:--------:|
| `Authorization` | `Bearer <token>` | Yes |
| `Content-Type` | `application/json` | Yes |

### Request Body

| Field | Type | Description | Required |
|-------|------|-------------|:--------:|
| `content` | string | Markdown content to publish | Yes |
| `slug` | string | Custom URL slug | No |
| `expiresIn` | number | Expiry in seconds (0 = permanent) | No |

### Example Request

```bash
curl -X POST https://api.mdtolink.com/api/documents \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello World\n\nThis is my document.",
    "slug": "hello-world"
  }'

Example Response

{
  "id": "doc_abc123",
  "url": "https://mdtolink.com/hello-world",
  "slug": "hello-world",
  "createdAt": "2026-03-04T10:00:00Z",
  "expiresAt": null
}

Error Responses

## Authentication Section Template

```markdown
## Authentication

All API requests require a Bearer token in the `Authorization` header.

### Getting an API Key

1. Sign in at [app.mdtolink.com](https://app.mdtolink.com)
2. Go to Settings > API Keys
3. Click "Create API Key"
4. Copy the key (it is only shown once)

### Using the Key

Include the key in every request:

```bash
curl https://api.mdtolink.com/api/documents \
  -H "Authorization: Bearer your-api-key"

Key Permissions

## Error Codes Section Template

```markdown
## Error Codes

All errors return a JSON body with `error` and `message` fields:

```json
{
  "error": "unauthorized",
  "message": "Invalid or expired API key."
}

HTTP Status Codes

Rate Limiting

The API allows 100 requests per minute per API key. When you exceed the limit:

• Response status: 429
• Retry-After header contains seconds to wait
• X-RateLimit-Remaining header shows remaining requests

## Quickstart Template

```markdown
## Quickstart

Publish your first document in 30 seconds.

### 1. Get an API Key

Sign in and create a key at [Settings > API Keys](https://app.mdtolink.com/settings/api-keys).

### 2. Publish a Document

```bash
curl -X POST https://api.mdtolink.com/api/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello World\n\nMy first published document."}'

3. Open the URL

The response includes a url field. Open it in your browser to see the published document.

## Tips for Writing API Docs

**Show, do not explain.** A `curl` example is worth more than three paragraphs describing the request format. Lead with the example, then explain the details.

**Use realistic examples.** Placeholder values like `"string"` and `"value"` force the reader to guess. Use realistic data:

```json
// Weak
{ "name": "string", "email": "string" }

// Better
{ "name": "Alice Chen", "email": "alice@example.com" }

Document every field. If a parameter exists, document it. Include the type, whether it’s required, and what the default is. Undocumented fields create confusion and support tickets.

Include error examples. Show what happens when something goes wrong, not just the happy path. Developers spend more time debugging errors than reading success responses.

Keep it current. Outdated API docs are worse than no docs. Update the documentation in the same pull request that changes the API.

Tools for API Documentation

For quick internal API docs or drafts, writing markdown and publishing via MDtoLink gets you a shareable URL in seconds. For public API documentation, a dedicated tool with versioning and interactive examples is worth the setup.

FAQ

What format should API documentation be in?

Markdown is the most common format for developer-facing API docs. It works with version control, renders on GitHub, and integrates with documentation tools. For interactive docs with a “try it” console, use OpenAPI/Swagger alongside your markdown docs.

How detailed should API docs be?

Document every endpoint, every parameter, every error code. Include request and response examples for each endpoint. Developers should be able to make their first successful API call using only the documentation.

Should I auto-generate docs from code?

Auto-generation from OpenAPI specs works well for reference documentation (endpoint lists, parameter tables). Combine it with hand-written guides for authentication, quickstarts, and common workflows. Auto-generated docs alone miss the “how” and “why.”

How do I keep API docs up to date?

Update docs in the same pull request that changes the API. Add documentation changes to your PR checklist. If your API has an OpenAPI spec, generate the reference docs from it to stay in sync automatically.

Try It Out

Write your API documentation in markdown and share it instantly. The MDtoLink editor previews your docs in real time. Publish to a shareable URL with one click using mdtolink publish api-docs.md.

For the full markdown syntax, see the markdown cheat sheet. For changelog formatting, see How to Write a Changelog.