API design review

Review this API design before it ships. Context on who calls it and how
it'll be used: {{context}}

Check specifically for:
1. Consistency - do similar operations use similar shapes (naming,
   pagination, error format, field casing) as the rest of this API, or
   does this endpoint/method do its own thing?
2. Evolvability - what happens when a field needs to be added, a type
   needs to change, or an operation needs to become async? Flag anything
   that would be a breaking change to fix later versus something that has
   room to grow.
3. Error handling - are error cases (not found, invalid input, conflict,
   rate limited) distinguishable by the caller, with enough information to
   act on, without leaking internal details they shouldn't see?
4. The "surprising to a new caller" test - is there any behavior a
   first-time caller would likely get wrong just from reading the
   interface, without reading the docs?

For each issue, say how bad it'd be to fix after external callers exist
(cheap/moderate/breaking) - that's what should drive priority.

API design:
{{api_description}}

When to use

Before an API ships, especially one that will have external or cross-team callers you can’t easily coordinate a breaking change with later. Internal-only APIs still benefit, just with lower stakes.

Why it works

Most API design mistakes are cheap to fix before anyone depends on them and expensive after - the review needs to prioritize by that axis, not by “this bugs me stylistically.” Asking specifically about evolvability surfaces the kind of design smell (a required field that should have been optional, a naked array response with no room for pagination metadata) that’s invisible in a design review of a single endpoint in isolation.

Variations

• Add “Compare this against {{similar API}}‘s conventions” if you’re extending an existing API family and want consistency checked against it specifically.
• For a GraphQL schema instead of REST, ask specifically about nullability choices and whether the schema over-fetches or under-fetches for the stated use case.
• Ask “What would this look like as a v2, assuming we could break compatibility?” as a separate follow-up, to separate “fix now” from “note for later.”