Design a RESTful API Endpoint Schema

This prompt puts the model in a senior backend engineer's seat and demands the full contract for each endpoint — method, path, params, request/response schemas, status codes, and at least two error cases — so you get something implementable rather than a sketch. Use it at the start of building a feature, when you want a reviewable API design before any code exists. The instruction to flag tricky tradeoffs is the high-value part: it surfaces the decisions a junior would silently get wrong.

What you can expect back

POST /teams/{teamId}/invitations
Path param: teamId (string)
Request body: { "email": "[email protected]", "role": "editor" }
Response 201: { "id": "inv_8f2", "email": "[email protected]", "role": "editor", "status": "pending", "expiresAt": "2026-06-22T00:00:00Z" }
Errors:
- 409 { "error": "already_member", "message": "User is already on this team." }
- 422 { "error": "invalid_role", "message": "Role must be one of admin, editor, viewer." }

POST /invitations/{token}/accept
Path param: token (opaque string from the email link)
Response 200: { "teamId": "team_31", "role": "editor" }
Errors:
- 410 { "error": "expired", "message": "This invitation has expired." }
- 404 { "error": "not_found", "message": "Invitation does not exist." }

Tradeoff: Accept is keyed by an opaque token rather than the invitation id, so an attacker who guesses an id can't accept on someone's behalf — at the cost of a separate non-RESTful-looking action path.

Illustrative example — your results will vary by tool and inputs.

Get sharper results

• 01State your auth model up front (JWT, session, API key) so the design includes 401 vs. 403 distinctions and ownership checks rather than leaving security implicit.
• 02Specify pagination, filtering, and sorting expectations for any list endpoint, or the model will default to returning everything unbounded.
• 03Ask it to use a consistent error envelope (e.g. always { error, message, details }) so your client can parse failures uniformly across endpoints.
• 04Request idempotency handling for POST/create endpoints if duplicate submissions are a real risk — it'll suggest an Idempotency-Key header pattern.
• 05Have it call out which fields are server-generated versus client-supplied so you don't accidentally let callers set ids or timestamps.

Adapt it for your case