Most API documentation is a complete list of endpoints and almost no explanation of how to accomplish anything. It is technically exhaustive and practically useless, because the reader does not arrive wanting a list, they arrive wanting to do one specific thing.
Lead with a working request
The first thing on the page should be a request someone can copy, paste, and run. Not a description of authentication concepts, an actual call, with an actual response next to it.
Document the failures
Every integrator will hit rate limits, expired tokens and validation errors. If those are not documented, each one becomes a support ticket. List the error codes, what causes them, and exactly what to do about each.
- What the rate limits are, and what happens when you exceed them.
- How long tokens last and how to refresh them.
- Which fields are required, and what a validation failure looks like.
- Whether retries are safe, and which operations are idempotent.
Skip what the reader can infer
You do not need a paragraph explaining that `created_at` is a timestamp. Spend that effort on the things that are genuinely non-obvious: pagination behaviour, sort stability, and what happens to related records on delete.
Good docs are judged by time-to-first-successful-call, not by page count.