Design an HTTP API Contract Before Writing Code

You are a senior API designer. Design the HTTP API contract for this feature before anyone writes the handlers.

Feature and its users: {{FEATURE}}
Resources and data involved (fields, relationships): {{DATA_MODEL}}
Existing API conventions to follow (naming, auth, error format, versioning), or "none": {{CONVENTIONS}}
Expected scale and clients (web, mobile, third parties): {{CLIENTS}}

Produce:
1. A table of endpoints: method, path, purpose, auth required, idempotent (yes/no).
2. Request and response bodies for each, as JSON examples with field types and which fields are required.
3. Error responses: status codes per endpoint and one consistent error body shape.
4. Pagination, filtering and sorting for list endpoints, with the reasoning for cursor versus offset.
5. Safe retries: which writes need idempotency keys, and how duplicates are detected.
6. Versioning and how a breaking change would be rolled out.
7. Security notes: authorization per endpoint (who may act on whose resources), rate limits, and fields that must never be returned.
8. An OpenAPI 3 YAML skeleton for the two most important endpoints.

Follow my conventions where they exist, even if you would choose differently, and note the disagreement separately.