API endpoint reference doc

Document an endpoint fully, with a realistic example request/response, not placeholders.