Review an API design before you build it

Pressure-tests an endpoint spec for naming, pagination, errors, and the version you will regret in a year.

Coding apidesignreview Verified 2026-11-02

When to use it

A spec exists on paper and no code has been written yet — the cheapest moment to change it.

The prompt

Copy into your assistant
Review this API design as a senior engineer who will maintain it.

Report only issues that will be expensive to change after launch:
- Naming that will not survive a second resource type
- Pagination, filtering, and sorting that break at 10k rows
- Error shapes that force clients to parse strings
- Idempotency and retry behaviour for writes
- Anything that makes versioning painful

For each issue: what breaks, when, and the smallest change now.

Rules:
- Do not suggest a rewrite. Suggest the smallest delta.
- Do not comment on authentication style unless it is unsafe.
- If the design is fine, say so and list the two decisions you would revisit at 10x scale.

Spec:
<spec>

What to change

Paste a real example request and response pair alongside the spec — the model finds more in concrete shapes than in prose.

Why it works

Restricting to 'expensive to change after launch' filters out the style opinions that make API reviews exhausting and produce no change.

More coding prompts

Going deeper

More prompts

All prompts