Design a REST Endpoint Contract Before You Code It

You are an API designer producing an endpoint contract a developer can implement without asking follow-up questions. Consistency with the existing API beats textbook purity.

<context>
The resource and action: [ACTION — e.g. create a booking / list invoices for a customer]
Fields involved, with types and which are required: [FIELDS — e.g. customer_id (uuid, required), starts_at (ISO 8601, required), notes (string ≤500, optional)]
Auth model: [AUTH — e.g. bearer JWT per user / API key per tenant]
Who consumes it: [CONSUMERS — e.g. our own React app and one partner integration]
Stack: [STACK — e.g. Express + Zod / FastAPI]
Existing conventions in this API: [CONVENTIONS — e.g. snake_case JSON, errors as {error: {code, message}}, cursor pagination — or 'none yet, set them']
</context>

Before writing the contract, decide and state: the correct method and path given REST semantics and my conventions; whether this operation should be idempotent and how (natural idempotency or an Idempotency-Key header — important for anything a flaky mobile client might retry); and the one design question you'd raise with the team if you could.

<task>
1. Method + path with two lines of reasoning, plus the path/query/body split for every input.
2. Request schema: every field with type, required/optional, validation rule and the exact 422/400 message a consumer sees when it fails — one per field, phrased so a frontend can display it.
3. Success response: status code choice explained (200 vs 201 vs 204), full example JSON body, and headers that matter (Location on creates).
4. Error catalogue: 400, 401, 403, 404, 409, 422, 429 and 500 — for each, when THIS endpoint returns it and an example body in my stated error convention. Omit any that genuinely can't occur and say why.
5. If it's a list: pagination, filtering and sorting parameters consistent with my conventions, with limits and defaults.
6. Two curl examples — one happy path, one that triggers validation errors — with expected responses.
7. Notes: rate-limit expectations, what gets logged versus what must never be (tokens, personal data), and the versioning stance.
</task>

<output_format>Contract document in the order above, ready to drop into the repo docs.</output_format>

Rules: use only my fields and conventions — never invent fields, and where a convention is unstated, propose one and mark it [DECIDE: …].

Copy the block above straight into Claude — anything in [BRACKETS] is yours to fill in.