These 14 API design prompts help ChatGPT, Claude, Claude Code and Codex design APIs that are pleasant to use and safe to change: resource models, naming, REST versus GraphQL, error responses, pagination, idempotent writes, versioning, deprecation and OpenAPI documents. Each prompt asks for concrete examples and the tradeoffs behind each choice.
For a single all-in-one "design an API" prompt, see the coding prompts collection. The prompts below go deeper on the decisions that are hard to undo once clients depend on them.
How to use these prompts
Copy a prompt into ChatGPT, Claude, Claude Code or Codex and fill the blanks in double braces. A blank with a colon has a default: {{style:REST}} means REST unless you change it.
Give the model real material. Paste your existing endpoints, an OpenAPI file, a sample response or the user stories, not a one-line summary. API design is mostly about consistency, and the model can only stay consistent with what it can see. In an agent, name the route files or the spec and let it read them.
Ask for examples, not just rules. A JSON request and response pair exposes awkward names and missing fields faster than any description. And always ask for the alternatives the model rejected: a design you understand is easier to defend in review.
How do you design the resource model?
1. Model resources from user stories
Start here before any endpoint exists. Nouns and relationships first, URLs second.
Here are the user stories for {{product:a team task tracker}}:
{{user_stories}}
1. List the resources (nouns) the API needs, with their key fields and how
they relate (one-to-many, many-to-many).
2. Propose URL paths for each resource. Nest only where a child can't exist
without its parent, and no deeper than two levels.
3. Map every user story to the requests a client would make.
4. Flag stories that don't fit a resource cleanly and suggest how to model
them (a sub-resource, a state field, or an action endpoint).
2. Write a naming guide for the API
Inconsistent names are the most common complaint about APIs. Fix them once, in writing.
Here are the current endpoints and a few sample responses from our API:
{{endpoints_and_samples}}
Write a short naming guide we can follow from now on, based on what we
already do most often:
- Plural or singular collection names
- Field case ({{case:camelCase}}) and how to name booleans, dates and IDs
- Date and time format (and time zone)
- How to name actions that don't fit create, read, update, delete
- Enum value style
Then list every place the current API breaks the guide, with the fix.
Mark which fixes would be breaking changes for existing clients.
3. Choose REST or GraphQL
Use it when the team is split. The prompt forces the argument back to your actual clients.
We're building an API for {{product}}. Clients: {{clients:a React web app, an iOS app and two partner integrations}}.
Typical screens or jobs and the data each needs:
{{screens_and_data}}
Compare REST and GraphQL for this case on: number of round trips per screen,
caching (HTTP and client side), authorization per field, rate limiting,
tooling for partners, and how hard each is to evolve. Recommend one, give the
two strongest arguments for the option you didn't pick, and say what would
make you change your mind.
How should errors, pagination and writes work?
4. Design error responses with Problem Details
RFC 9457 defines a standard error object for HTTP APIs, so clients can handle every endpoint's errors the same way.
Design the error responses for our {{framework:Express}} API using RFC 9457
Problem Details (application/problem+json, with type, title, status, detail
and instance).
Endpoints:
{{endpoints}}
Give me:
1. A table of error cases: HTTP status, problem type URI, title, when it
happens.
2. A JSON example for a validation error that lists each invalid field and
why, using an extension member.
3. Which details are safe to show clients and which must only go to logs.
4. A small helper function that builds these responses in {{framework:Express}}.
5. Design pagination for a list endpoint
Offset pagination is easy until rows are added mid-scroll. This prompt makes the model pick deliberately.
Design pagination for GET {{path:/v1/orders}}. The table has about
{{rows:5 million}} rows, new rows arrive constantly, and clients
{{usage:scroll through recent orders and sometimes jump to a date}}.
Compare offset and cursor pagination for this case, then pick one. Show:
- Query parameters, with defaults and the maximum page size
- The response shape, including how the client gets the next page
- How the cursor is built and why clients must treat it as opaque
- The database query and index that keeps each page fast
- What happens when the sort field has duplicate values
6. Add filtering, sorting and field selection
For list endpoints that keep growing ad hoc query parameters.
Our list endpoint {{path:/v1/products}} needs filtering, sorting and a way to
return fewer fields. Current parameters: {{current_params:none}}.
Fields clients filter or sort on: {{fields}}
Propose one consistent syntax for: equality and range filters, multiple
values, sort order with several fields, and selecting fields. Show five
example URLs, how each maps to a database query, which fields need an index,
and which filters to refuse because they can't be served fast.
7. Make writes safe to retry
Networks fail after the server has done the work. Idempotent writes stop retries from charging a card twice.
Clients retry {{operation:POST /v1/payments}} when a request times out, and
we've seen duplicates. Design idempotency for this endpoint.
Cover:
- How the client sends an idempotency key and what makes a good key
- What the server stores, for how long, and where
- What to return when the same key arrives with the same body, with a
different body, and while the first request is still running
- How this interacts with our database transaction
- Which other endpoints in this list need the same treatment: {{endpoints}}
How do you design a GraphQL schema?
8. Draft a GraphQL schema from screens
GraphQL schemas work best when they follow what clients render, not the database tables.
Draft a GraphQL schema for {{product}} from these screens and the data each
one shows:
{{screens}}
Include types, queries, mutations with input types, and connection-style
pagination for lists. Decide nullability on purpose and explain the rule you
used. Show the query each screen would send. Point out where our database
tables ({{tables}}) differ from the schema and why that's fine.
9. Review a GraphQL schema for production
For a schema that works in development but hasn't met real traffic. Broken object level authorization is item one in the OWASP API Security Top 10, and GraphQL makes it easy to miss on nested fields.
Review this GraphQL schema and resolver outline before we launch.
{{schema}}
Check for: N+1 queries in resolvers and where batching is needed, missing
limits on list fields, query depth or cost limits, fields that need
per-object authorization, nullability that will break clients when a backend
fails, and mutations that should return the changed object. List each issue
with severity and the fix.
How do you version and change an API?
10. Pick a versioning strategy
Decide this before the first external client, not after.
We're about to publish {{api:our public REST API}} to {{consumers:paying customers who integrate once and rarely update}}.
Compare URL path versions (/v1), a header or media type version, and
date-based versions for our case. For the option you recommend, explain:
what counts as a breaking change, how long we support an old version, how
clients learn about changes, and how we run two versions in one codebase
without copying everything.
11. Check a change for breaking changes
Run it on every pull request that touches the API contract.
Here are two versions of our OpenAPI document: before and after a change.
Before:
{{old_spec}}
After:
{{new_spec}}
List every difference and classify each one as breaking, risky or safe for
existing clients. Breaking includes removed or renamed fields and endpoints,
new required inputs, narrowed types or enums, changed status codes and
stricter validation. For each breaking change, suggest a non-breaking way to
get the same result.
12. Plan a deprecation
For removing an endpoint or field without surprising anyone.
We want to remove {{thing:the v1 /users/search endpoint}}. Replacement:
{{replacement}}. Known callers: {{callers:unknown, roughly 40 API keys use it each week}}.
Write a deprecation plan: how we signal it in responses and docs, a timeline
with dates relative to today, how we find and contact the callers, what we
measure before turning it off, and a short migration guide with a before and
after request example.
How do you document and review an API?
13. Write an OpenAPI document from the code
Best in an agent that can read the route files. The current OpenAPI Specification is 3.2.1 as of October 2026; pick the version your tools support.
Read the route handlers and validation schemas in {{path:src/routes}} and
write an OpenAPI {{version:3.1}} document in YAML for them.
For every operation: summary, parameters, request body, every response status
the code can return, and one example per response. Reuse shared schemas under
components. Mark anything you inferred instead of reading in the code with a
"x-inferred: true" extension so I can check it, and list any handler you
couldn't document.
14. Review an API as a new consumer
The fastest way to find friction: pretend to be the developer integrating it tomorrow.
Act as a developer integrating our API for the first time. Here is the
OpenAPI document or docs:
{{spec}}
Your task is to {{task:create a customer, attach a payment method and charge it}}. Write the sequence of requests you'd make, and every point where you'd
be confused, need to guess, or need two calls where one should do. End with
the five changes that would most improve the experience, ranked.
How do you keep API design consistent across a team?
A prompt only helps when someone remembers to run it. If your team designs APIs often, turn the naming guide and the breaking change check into a skill so the agent applies them on every change. The API design skill page covers one ready-made option, and the SKILL.md generator turns any prompt above into a valid SKILL.md in your browser.
Pair these with the documentation prompts for endpoint reference docs and the security review prompts for checking authorization on every route.
To keep prompts like these close, save them in Kipt. Your prompts live as Markdown in a private GitHub repo you own, the double-brace blanks stay fillable, and Cmd+K finds any prompt by name or tag. When one becomes a skill, Kipt can install every skill in your library into Claude Code or Codex with one npx skills add command.