Cursor rules for documenting API endpoints

A style guide works best when it shows up while people are writing. This rule file puts ours inside the editor: when a developer asks Cursor to document a new endpoint, the output already follows our structure, voice and terminology.

Writing sample. This is an illustrative rule file I wrote for this portfolio, based on the approach I use at work. It isn’t a copy of any employer’s internal rules.

The problem it solves

Developers write the first draft of most endpoint docs. Without guidance, every endpoint comes out different: some have error tables, some don’t, and a “participant” turns into a “partner” and then a “client”. Reviewing that one PR at a time doesn’t scale for a team of one writer.

The rule file

Save this file as .cursor/rules/api-endpoint-docs.mdc in the docs repository:

---
description: Use when writing or editing documentation for an API endpoint
globs: ["docs/api/**/*.md"]
alwaysApply: false
---

# Documenting an API endpoint

You are helping a developer document a REST endpoint for external
participants. Follow this structure exactly. Don't add or remove sections.

## Required sections, in this order
1. `# <Verb> a <resource>`: title in sentence case, e.g. "Create a payout".
2. One-sentence summary. Start with a verb and describe the
   real-world outcome, not the object returned.
3. Method and path badge: `POST /v1/payouts`
4. `## Before you begin`: scopes, prerequisites, required objects.
5. `## Headers`: table with columns Header | Required | Description.
6. `## Request body`: table with columns
   Parameter | Type | Required | Description.
7. `## Example request`: one runnable curl example.
8. `## Example response`: realistic JSON with HTTP status stated above it.
9. `## Errors`: table with columns
   HTTP status | Error code | What happened | What to do.

## Writing rules
- Use second person ("you") and active voice. Use the present tense.
- Parameter descriptions: what it is → example → constraints/defaults.
- Don't use "simply", "just", "easily", "please", or Latin abbreviations.
- Write amounts as integers in minor units and explain this once.
- Use placeholders like $ACCESS_TOKEN. Never output real credentials.

## Terminology (always use the left-hand term)
- participant (not partner, member, client)
- sign in (not log in)
- select (not click)

## Before finishing
- If a field's behaviour is unclear from the code or spec, insert
  `<!-- TODO(writer): confirm ... -->` instead of guessing.
- Remind the developer to test the example request in Postman
  before opening the PR.

Design decisions

Decision	Why
Scoped with `globs`	The rule only applies to API docs, so it doesn’t interfere with code or other content.
Exact section order	Consistent structure is what makes a reference scannable. Readers learn where errors live once.
“Insert a TODO instead of guessing”	The most important line. It stops the model from inventing behaviour, and flags gaps for the writer to confirm with engineering.
Terminology as a short list	Models follow short, explicit lists far better than prose guidance.
Reminder to test in Postman	AI can draft an example, but only a human with a sandbox can prove it works.

Results I look for

Developer drafts arrive already structured, so my review focuses on accuracy and clarity instead of formatting.
Terminology drift drops, because the right term is in front of the model every time.
TODO markers turn unknowns into specific questions for engineers, instead of confident mistakes.

Was this page helpful?