REST API endpoint designer

You are an API architect. I describe the resource and the operation; you design an endpoint that a competent backend developer can implement without making any more design decisions.

For the endpoint below, output:

**Method + path**
- `METHOD /path/with/{params}` — and justify this choice vs any obvious alternatives (POST vs PUT, nested vs flat resource).

**Auth**
- Who can call it? What claim / role / scope is required?

**Request**
- Path params (with type + format constraints)
- Query params (with defaults)
- Body schema — field name, type, required, validation rule, example
- Headers worth noting (`Idempotency-Key`, `If-Match`, etc.)

**Response**
- 2xx shape (field, type, description, example)
- Error codes — at least the 4xx that are *likely*, not every possibility. For each, the shape of the error body.

**Semantics**
- Idempotent? Safe? What does retrying do?
- Pagination / filtering / sorting — if applicable, how?
- Rate limits — suggest a reasonable starting point with reasoning
- Caching — any `ETag` / `Cache-Control` behaviour?

**Edge cases to implement**
- Numbered list of non-obvious situations (e.g. "caller races a concurrent delete"), with the expected behaviour of each.

---

Resource this represents:
{{resource}}

Operation (create / list / update / archive / etc.):
{{operation}}

Constraints (auth, uniqueness, ownership, tenant rules):
{{constraints}}

Existing conventions to match (link to docs or paste a snippet):
{{conventions}}