API Documentation Baseline Review

Your API docs look fine until a developer tries to use them and gets stuck. This reviews the docs for one endpoint against a strict checklist: every parameter named, typed and given an example, auth explained, status codes in plain English, a full request-and-response sample. You get a list of exactly what is missing.

Review the following API documentation for the {ENDPOINT_NAME} endpoint: {API_DOCS_DRAFT}.

Evaluate it against these criteria: Does each parameter have a name, type, whether it is required, a description, and an example value? Is the authentication method explained with a working example? Are HTTP status codes listed with plain-English meanings? Is there a complete request-and-response example in {CODE_LANGUAGE}? Are rate limits and error handling documented?

For each criterion, give a pass/fail rating and a one-sentence fix recommendation. Prioritise fixes by user impact: most confusing gaps first. Finally, provide a rewritten version of the worst-performing section as a model for the team to follow.