API Documentation Markdown Template

Describe API authentication, endpoints, requests, responses, errors, pagination, and rate limits with copyable Markdown examples.

Markdown

# Example API Documentation

All URLs and payloads below are examples. Replace them with verified API behavior.

## Base URL

`https://api.example.com`

## Authentication

Send a bearer token over HTTPS:

```http
Authorization: Bearer $API_TOKEN
```

Do not publish a real token.

## Get an example user

`GET /v1/users/{user_id}`

### Path and query parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :---: | :--- |
| `user_id` | path | string | Yes | Example user identifier |
| `include` | query | string | No | Related fields to include |

### curl request

```bash
curl --request GET \
  --url "https://api.example.com/v1/users/example-user?include=profile" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json"
```

### Example response

```json
{
  "id": "example-user",
  "display_name": "Example User",
  "profile": {
    "status": "example"
  }
}
```

## Create an example user

`POST /v1/users`

### Example request body

```json
{
  "display_name": "Example User"
}
```

Document the success status, response headers, and response schema here.

## Errors

| Status | Code | Meaning | Suggested handling |
| :---: | :--- | :--- | :--- |
| 400 | `invalid_request` | Example validation failure | Correct the named field |
| 401 | `unauthorized` | Missing or invalid credentials | Refresh or replace the token |
| 404 | `not_found` | Resource was not found | Verify the identifier |
| 429 | `rate_limited` | Request limit reached | Honor the documented retry header |

Show the verified error envelope here.

## Pagination

Document the pagination style, default and maximum page size, ordering, and next-page field. Add a labeled example response.

## Rate limits

Document the actual quota, scope, reset window, response headers, and retry guidance. Do not guess limit values.

Preview

Example API Documentation

All URLs and payloads below are examples. Replace them with verified API behavior.

Base URL

https://api.example.com

Authentication

Send a bearer token over HTTPS:

Authorization: Bearer $API_TOKEN

Do not publish a real token.

Get an example user

GET /v1/users/{user_id}

Path and query parameters

Name	In	Type	Required	Description
`user_id`	path	string	Yes	Example user identifier
`include`	query	string	No	Related fields to include

curl request

curl --request GET \
  --url "https://api.example.com/v1/users/example-user?include=profile" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json"

Example response

{
  "id": "example-user",
  "display_name": "Example User",
  "profile": {
    "status": "example"
  }
}

Create an example user

POST /v1/users

Example request body

{
  "display_name": "Example User"
}

Document the success status, response headers, and response schema here.

Errors

Status	Code	Meaning	Suggested handling
400	`invalid_request`	Example validation failure	Correct the named field
401	`unauthorized`	Missing or invalid credentials	Refresh or replace the token
404	`not_found`	Resource was not found	Verify the identifier
429	`rate_limited`	Request limit reached	Honor the documented retry header

Show the verified error envelope here.

Pagination

Document the pagination style, default and maximum page size, ordering, and next-page field. Add a labeled example response.

Rate limits

Document the actual quota, scope, reset window, response headers, and retry guidance. Do not guess limit values.

When to use this template

Use this for a REST endpoint reference that must be readable in a repository or documentation site. It works best alongside an authoritative API specification rather than replacing one.

Section guide

Base URL and authentication: Define the request context and credential format once.
Endpoint request and response: Show a complete, copyable interaction and label example data.
Errors and limits: Explain predictable failure, pagination, and throttling behavior.

How to use this template

1
Copy the Markdown
Click the Copy button above to put the full template on your clipboard.
2
Paste into your editor
Paste into the mdkit editor, a repository, a notes app, or another Markdown editor. Check tables and task lists in your target renderer because Markdown support varies.
3
Fill in your content
Replace bracketed examples with verified information, adapt fields to your context, and remove sections that do not apply.
4
Export or share
Review sensitive information, links, facts, and formatting. Then commit to Git, share the Markdown, or export to HTML or PDF.

Check before you use it

The endpoint, schema, status codes, and limits are placeholders; verify them against the implementation.
Never paste a real token into documentation, screenshots, or command history.

Template details

What it solves

Consumers need an explicit contract for constructing requests and handling responses, including failures and collection behavior.

Key features

Example base URL and bearer-token header
Copyable curl request with path and query parameters
Labeled example request and response payloads
Error, pagination, and rate-limit placeholders

Pro tips

>Redact secrets and use environment variables in every command.
>Keep examples synchronized with schema or contract tests.
>Document only status codes and headers the API actually returns.

Useful Markdown tools

Start in the Markdown editor, then use a relevant tool when you need to format or export the finished document.

Markdown table generator Markdown to HTML converter