Verified against Cursor · 2026-08-08
Brief Cursor's Agent mode to design a REST endpoint from a contract, not from whatever shape falls out of the handler
A contract-first REST endpoint brief for Agent mode that pins down resource semantics, status-code mapping, and error-body shape before implementation starts, so the eventual handler matches an agreed contract instead of whatever shape came out naturally while wiring up the route.
The prompt
Ready to copy — highlighted parts are example details you can swap.
You are designing and implementing a new REST endpoint in Agent mode. Do not start editing route handlers until the contract below is fixed — treat it as the spec the implementation has to match, not a draft you can quietly adjust once the code turns out easier to write one way than another.
ENDPOINT
POST /api/v1/orders/:orderId/refunds
RESOURCE SEMANTICS
Creates a partial or full refund against an already-captured payment. Idempotent per idempotency key; does not cancel or modify the original order.
REQUEST SHAPE
{ amount: number (cents, > 0, <= remaining captured amount), reason: 'customer_request' | 'duplicate' | 'fraudulent', idempotencyKey: string }
RESPONSE SHAPE (SUCCESS)
{ refundId: string, orderId: string, amount: number, status: 'pending' | 'succeeded', createdAt: string (ISO 8601) }
ERROR CASES AND STATUS CODES
amount exceeds remaining captured amount -> 422 { code: 'amount_exceeds_captured' }; order not found -> 404; duplicate idempotency key with a different body -> 409; order not yet captured -> 409 { code: 'not_captured' }
EXISTING API CONVENTIONS TO MATCH
All errors return { error: { code, message } }. Auth is a Bearer token checked by requireAuth() middleware, never re-implemented per route.
BEFORE WRITING THE HANDLER
Restate the contract above back in one paragraph, in your own words, and flag anything ambiguous now — a status code not covered by an error case that could plausibly happen, a field whose type isn't fully specified. Do not proceed to implementation while an ambiguity is unresolved by quietly picking the version that's easiest to code.
IMPLEMENTATION RULES
- Validate the request shape at the boundary before any business logic runs; reject with the error case that matches, not a generic 400.
- Match the existing API conventions exactly for error body shape, pagination, and auth handling — a technically-fine response using a different error envelope than every other endpoint in this API is still wrong.
- Do not add a field to the response that isn't in RESPONSE SHAPE, even if it seems obviously useful — name it and ask, since an extra field becomes a de facto contract the moment a client starts depending on it.
- Do not silently narrow an error case to a subset of what it should cover (handling one invalid-input variant but not the sibling one in the same case) just because you found one first while testing.
WHEN DONE
List each error case from above and the exact status code and body the handler now returns for it, so the contract can be checked case by case rather than trusted from a summary. Separately, list any endpoint behavior you added beyond what's stated here.Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
Agent mode reads the surrounding framework and ORM conventions and will happily let a response shape emerge from whatever the handler naturally produces — a serialized model, a wrapped query result — rather than from a contract that was actually agreed on, which means the eventual response can drift from what a client was built against without either side noticing until an integration breaks. Fixing the contract before any file is touched, and requiring the model to restate it and surface ambiguity first, forces that negotiation to happen as a checkable paragraph rather than as an implicit decision baked silently into working code, which is a much harder thing to renegotiate once a client has already started depending on it. The explicit ban on adding an unrequested response field targets a specific and common agent habit: proactively enriching a response with a field that seems obviously useful — a computed total, a related object — reads as helpful in isolation, but the moment any client starts reading that field, it has become part of the contract whether or not it was ever agreed to be, and removing it later is now a breaking change nobody planned for. Requiring the exact status code and body to be listed per stated error case, rather than a general claim that errors are handled, converts "handles errors" from an unverifiable summary into something that can be checked line by line against the original list — which is also what catches the common failure mode of one error case actually covering two sibling conditions in the contract but the implementation only reaching the one that came up first during manual testing.
What you get back
Contract restated: this is a per-order partial/full refund, idempotent on idempotencyKey, requiring the order to already be captured. Ambiguity flagged: REQUEST SHAPE doesn't say what happens if amount is omitted entirely — treating it as "full remaining amount" unless told otherwise, flagging this assumption explicitly.
Error case coverage: - amount exceeds remaining captured amount -> 422 { error: { code: 'amount_exceeds_captured', message } } - order not found -> 404 { error: { code: 'not_found', message } } - duplicate idempotency key, different body -> 409 { error: { code: 'idempotency_conflict', message } } - order not yet captured -> 409 { error: { code: 'not_captured', message } }
No fields added beyond RESPONSE SHAPE.
Verified against
Cursor 2.2 · 2026-08-08
Changelog
- 2026-08-08 — Initial publish, verified against Cursor 2.2 Agent mode.
Need this built into your business?
If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
