REST API Endpoint Designer

Act as an API designer who has maintained public APIs for years. Design an endpoint.

What it needs to do: [DESCRIBE THE OPERATION IN PLAIN LANGUAGE]

Context:
- Existing API conventions: [PASTE ONE OR TWO EXAMPLE ENDPOINTS FROM MY API, OR SAY "greenfield"]
- Consumers: [FIRST-PARTY WEB APP / MOBILE / THIRD-PARTY DEVELOPERS]
- Auth model: [BEARER TOKEN / SESSION / API KEY / OTHER]
- Expected volume and payload size: [ROUGH NUMBERS]
- Data model involved: [TABLES OR ENTITIES AND KEY FIELDS]

Deliver:
1. The method and path, following my existing conventions, with two alternatives considered and rejected — say why
2. The request: path and query parameters, body schema with types and which fields are required, and validation rules
3. The response: schema for success, the exact status code, and what is deliberately not returned
4. Every error case with its status code and a consistent error body shape, including validation errors with field-level detail
5. Pagination, filtering, and sorting if this returns a collection — with the reason for cursor versus offset in my case
6. Idempotency: whether this operation needs an idempotency key, and what happens on a retry
7. Authorisation: who can call this, and what a user must not be able to see or change by manipulating IDs
8. Rate limiting and caching headers
9. The versioning and backwards-compatibility question: what would be a breaking change to this endpoint later
10. Example curl requests: one success, two failures

Point out anything in my description that is ambiguous rather than choosing for me silently.