Skip to content
Folio

API Reference Template (Markdown) for One Endpoint

An API documentation template in plain Markdown for one endpoint. It opens with the method and path, a table of owner, version and source, and then covers authentication, parameters, a request and a response example you can run, the error table, limits and a changelog. Copy it, download the .md file, or keep it in the repository next to the handler.

Free to use, no attribution required (CC0).

Open in Folio demo

API reference: {{GET /v1/resources/:id}}
API {{Service or API name}}
Version {{v1}}
Stability {{Stable / Beta / Deprecated}}
Owner {{Name or team}}
Source {{Link to the handler, the OpenAPI file or the pull request}}
Added in {{Version or date}}
Last reviewed {{YYYY-MM-DD}} by {{Name}}
Next review {{YYYY-MM-DD}}

{{One sentence: what this endpoint does and when to use it.}}

Describe the behaviour, not the implementation. If this page sits next to a generated reference, write only what a spec cannot say: when to use it, limits, edge cases and history.

Authentication and limits

  • Authentication: {{Bearer token in the Authorization header / API key}}
  • Permission or scope: {{Role or scope required}}
  • Rate limit: {{N requests per minute per token}}
  • Idempotent: {{Yes / No; how to make a retry safe}}

Request

{{GET}} {{/v1/resources/:id}}
Authorization: Bearer {{token}}
Accept: application/json
Path parameters
Name Type Description
{{id}} {{string}} {{What it identifies, format and constraints}}
Query parameters
Name Type Required Default Description
{{expand}} {{string}} {{No}} {{none}} {{Allowed values and what each does}}
Body

Delete this section for GET and DELETE. Say what is allowed (range, length, format), not only the type.

Field Type Required Description
{{name}} {{string}} {{Yes}} {{1 to 80 characters}}

Example

Run the request against a real environment, paste the real response, then replace tokens and personal data with fake values.

curl "https://api.example.com/v1/resources/res_123" \
  -H "Authorization: Bearer $API_TOKEN"

{
  "id": "res_123",
  "name": "Example resource",
  "created_at": "2026-01-15T09:30:00Z"
}

Response

Status: {{200 OK}}

Field Type Description
{{id}} {{string}} {{...}}
{{created_at}} {{string}} {{ISO 8601 timestamp in UTC}}

Errors

Status Code Meaning What the client should do
{{400}} {{invalid_request}} {{...}} {{Fix the request}}
{{401}} {{unauthorized}} {{...}} {{Check the token}}
{{404}} {{not_found}} {{...}} {{...}}
{{429}} {{rate_limited}} {{...}} {{Wait and retry with backoff}}

Behaviour and edge cases

  • {{Ordering, pagination, caching or eventual consistency}}
  • {{What happens on a repeated request}}
  • {{Size, time or count limits}}

Changelog

Version Date Change
{{v1}} {{YYYY-MM-DD}} {{Added}}

See also

  • {{Guide that uses this endpoint}}
  • {{Related endpoint}}

Review checklist

Tick before you ask for a review. Keep the list for the next reviewer or delete it when the page is published.

  • The request and response examples were run against a real environment and match
  • Every parameter and field in the code or the spec is on this page, and the other way round
  • The error table covers every status code the handler can return
  • Examples use fake values: no real tokens, hosts or customer data
  • A breaking change is in the changelog and in the release notes
  • The source link, the version and the stability in the table are current
  • Owner, last reviewed and next review are filled in

Want to see it as a real wiki page? Open this template in the Folio demo, where it is a normal Markdown page.

How to use it

  1. Step 1: Make one page per endpoint. Put the method and path in the title. Fill in the table at the top first: version, stability, owner and the link to the handler or the OpenAPI file that is the source.

  2. Step 2: Run the examples before you paste them. Send the request against a real environment, copy the real response, then replace tokens and personal data with fake values. Fill the parameter and error tables from the code, not from memory.

  3. Step 3: Compare with the code, then tick the review checklist. Every parameter and status code in the code must be on the page, and the other way round. Put breaking changes in the changelog and in the release notes.

What makes a good API reference

It is complete and exact. Every parameter has a type, whether it is required, its allowed values and a default. "String" is not a description: "UUID of the project, lowercase" is. The reader should never have to try a request to find out what is accepted.

Its examples are real. A request the reader can copy and a response that matches what the API returns today. Examples that were never run are the most common source of wrong documentation, and readers trust them first.

It documents errors as carefully as success. One row per status code the endpoint can return, with the meaning and what the client should do next. Retry on 429 and 503, fix the request on 400 and 422.

It keeps one source of truth. If you generate reference pages from an OpenAPI file, keep that file as the source and write by hand only what a spec cannot say: behaviour, limits, history and the reasons. If you write pages by hand, link to the code and re-check them when it changes.

More templates

How-to guideGoal in the title, prerequisites, one-action steps with expected results, a check and a review list.Release notesHighlights, new, improved, fixed, breaking changes and upgrade steps for each release.Troubleshooting guideFrom the exact symptom to the cause and the fix, known issues, and what to send to support.
All templates

Questions

What should API documentation include?
Authentication, the endpoint with its method and path, parameters with types and constraints, a request example, a response example, the error codes, rate limits and a changelog. This template has a section for each.
What is the difference between an API reference and an API guide?
A reference lists every endpoint and parameter exactly, for lookup. A guide walks through a task, such as "create a project and invite a user", across several endpoints. Write both, and link from each reference page to the guides that use it.
Should I write API docs by hand or generate them from OpenAPI?
Generate the parts that are mechanical (paths, types, required fields) and keep them in step with the code. Write by hand the parts that need judgment: when to use the endpoint, limits, edge cases and examples. This template suits the handwritten pages and the notes that sit next to a generated reference.
How do I document API versions and breaking changes?
Put the version in the table at the top and every change in the changelog at the bottom of the page. Mark breaking changes clearly, say what replaces the old behaviour, and repeat them in the release notes.
How do I keep API docs up to date?
Store them next to the code and review them in the same change as the code. Put an owner and a review date on each page, and add "update the reference" to the checklist of every pull request that changes an endpoint.

Updated 13 October 2026.

API pages in the repository, reviewed with the code

In Folio an API reference page is a Markdown file in Git, so it can live in the same repository as the service it describes. Code blocks for requests and responses, tables for parameters and errors, and checkboxes for the review list all render in the editor, and the page history shows who changed a field and when. You can write the page by hand, ask the built-in assistant to draft it, or let an MCP client read and update it with a personal token. Run the examples and read the result before you publish.

Open in Folio demoInstall FolioFolio on GitHub