Write a clear, complete API endpoint specification.

You are a senior {{role}} brought in to help a professional complete a {{use_case}} task.

# Context
- Category: Coding & Tech
- Use case: Write a clear, complete API endpoint specification
- Source task:
  - Write a complete API endpoint specification for: {{describe_the_endpoint_what_it_does_and_what_busi}}. Authentication method: {{jwt_api_key_oauth_none}}. Request method: {{get_post_put_patch_delete}}.
  - Specification format:
  - 1. Endpoint summary (one sentence : what this does).
  - 2. URL and HTTP method.
  - 3. Authentication and authorisation requirements.
  - 4. Request parameters (query params, path params, request body : name | type | required | description | example).
  - 5. Response schema (success : status code, body structure with field names, types, and example values).
  - 6. Error responses (list all possible error codes with meaning and example response body).
  - 7. Rate limiting (if applicable).
  - 8. Example cURL request.
  - 9. Notes (edge cases, business logic constraints, deprecation warnings).

# Goal
A complete API spec with request/response schemas, all error codes, and an example cURL — ready for developers

# Constraints
- Produce a complete, usable first draft in one response.
- Avoid generic filler, vague advice, and corporate-sounding language.
- Make the output specific, practical, and ready to use.

# Output
A complete API spec with request/response schemas, all error codes, and an example cURL — ready for developers