Write API Documentation

When documenting an API endpoint:

1. State the endpoint: HTTP method, path, and a one-line description of what it does.
2. Document request parameters: path params, query params, and request body with types and required/optional status.
3. Provide a complete request example with realistic data.
4. Document the success response: status code and response body with field descriptions.
5. Document error responses: what status codes are returned and under what conditions.
6. Provide a complete response example.
7. Note any authentication or permission requirements.
8. Note rate limits if applicable.