30 Claude Prompts for API Specs

You are a principal API designer who names resources so URLs stay stable for years and stay obvious to a new engineer on day one. <context> I have a list of product nouns and actions, and I need a URL map before we start writing OpenAPI paths. I do not want verbs in the path unless there is no noun that fits. </context> <inputs> - Product nouns: [NOUN LIST] - User actions: [ACTION LIST] - Existing paths we cannot break: [EXISTING PATHS] - Collection style we already use: [PLURAL NOUNS OR MIXED] - Tenant scope: [TENANT SCOPE] </inputs> <task> Propose a resource and URL map: collection paths, item paths, and sub-resources. Call out any action that should be a verb path versus a field change on an existing resource. </task> <constraints> Prefer plural nouns and nest only one level unless a child cannot exist without the parent. Do not rename an existing path. If two nouns collide, pick one and explain why. Keep paths lowercase and hyphenated. </constraints> <format> Return a table of action, method, path, and rationale, then a short list of names you rejected and why. </format>

You are a senior backend engineer who reviews whether product asks map to the right HTTP method and status codes before the spec is published. <context> I have a set of product operations that were written as user stories, and I need each one mapped to a method and a success status so the frontend and backend stop arguing in Slack. </context> <inputs> - Operations to map: [OPERATION LIST] - Idempotency expectation: [IDEMPOTENT OR NOT] - Partial update need: [PATCH OR PUT] - Async jobs: [ASYNC JOB LIST] - Current frontend assumption: [FRONTEND ASSUMPTION] </inputs> <task> Map each operation to a method, success status, and failure statuses. Flag any operation that should be 202 with a job resource instead of a synchronous 200 or 201. </task> <constraints> Do not use 200 for a create. Do not use PUT if the client cannot send the full resource. Call out any mismatch with the frontend assumption. Keep the map implementable in a typical REST stack. </constraints> <format> Return a table with columns for operation, method, success status, failure statuses, and a one-line note. End with questions that still need a product call. </format>

You are an API product owner who writes list-endpoint contracts that stay the same across every collection in the product. <context> We have three list screens that each invented their own query params. I need one contract for filter, sort, and pagination that new endpoints can copy. </context> <inputs> - Collection name: [COLLECTION NAME] - Filterable fields: [FILTER FIELDS] - Sortable fields: [SORT FIELDS] - Default page size: [DEFAULT PAGE SIZE] - Pagination style we prefer: [CURSOR OR OFFSET] </inputs> <task> Write the query parameter contract and the list response envelope, including how empty pages, unknown filters, and oversize page requests are handled. </task> <constraints> Pick one pagination style and do not mix cursor and offset on the same collection. Unknown filters must fail closed with a 400, not be ignored. Cap page size. Keep parameter names consistent with the rest of our API if I named a style. </constraints> <format> Return a parameter table, a sample request URL, a sample JSON envelope, and a five-rule style guide other endpoints should follow. </format>

You are a distributed systems engineer who specifies write semantics so retries from mobile and payment clients do not create duplicate records. <context> Our create-order path is called from a flaky mobile network. I need the spec to state how idempotency keys work and what a replay returns. </context> <inputs> - Write endpoint: [WRITE ENDPOINT] - Idempotency header name: [IDEMPOTENCY HEADER] - Key lifetime: [KEY LIFETIME] - Conflicting replay behavior: [CONFLICT BEHAVIOR] - Side effects on create: [SIDE EFFECTS] </inputs> <task> Write the write-semantics section for this endpoint: required headers, stored key scope, response on first success, response on a matching replay, and response on a conflicting replay. </task> <constraints> Be explicit about whether a replay returns the original body and status. State what happens if the key expires mid-retry. Do not assume the client can safely POST twice. Mention side effects so product knows what a duplicate would cost. </constraints> <format> Return a spec section with subsections for Header, First write, Replay, Conflict, and Expiry, plus a short client implementation note. </format>

You are an API strategist who decides when a child should live under a parent path and when it should be a top-level resource with a foreign key. <context> I am specifying comments on tickets and I am not sure whether /tickets/{id}/comments or /comments?ticketId= is the right long-term shape. </context> <inputs> - Parent resource: [PARENT RESOURCE] - Child resource: [CHILD RESOURCE] - Access pattern: [ACCESS PATTERN] - Lifecycle rule: [CHILD LIFECYCLE] - Existing client consumers: [CLIENT LIST] </inputs> <task> Recommend nested versus flat, with a path set for the recommended option and a migration note if we later need the other shape. </task> <constraints> If a child is queried across parents, lean flat. If a child cannot exist without the parent and is always listed in that context, lean nested. Do not recommend both as first-class without a reason. Keep the recommendation to one primary shape. </constraints> <format> Return the recommendation in one paragraph, then the path table, then a list of client impacts for the consumers I named. </format>

You are an API governance lead who has shipped both URI versioning and header versioning and can explain the tradeoffs to a product manager without a slide deck. <context> We are about to publish a public API and I need a written decision on /v1 versus an Accept-Version header before we cut the first client SDK. </context> <inputs> - Audience: [PUBLIC OR PARTNER] - Client types: [CLIENT TYPES] - Expected breaking-change rate: [CHANGE RATE] - Gateway we use: [API GATEWAY] - Existing URL style in the company: [EXISTING URL STYLE] </inputs> <task> Recommend URI versioning, header versioning, or a hybrid. Write the decision, the default for new endpoints, and how a client opts into a new version. </task> <constraints> Pick one primary approach. Do not recommend both as equals. Account for the gateway I named. Mention cache and CDN behavior. Keep the memo under 400 words and free of vendor marketing. </constraints> <format> Return a decision memo with sections for Recommendation, Why, How clients opt in, and What we will not support in year one. </format>

You are a technical writer who maintains API changelogs that partner engineers actually read before they upgrade a client. <context> We are shipping a breaking change on a public endpoint and I need a changelog entry that states what breaks, what to do, and when the old shape dies. </context> <inputs> - Endpoint: [ENDPOINT PATH] - Current version: [CURRENT VERSION] - Next version: [NEXT VERSION] - What changed: [CHANGE LIST] - Sunset date: [SUNSET DATE] </inputs> <task> Write a changelog entry that a partner engineer can act on: old versus new request and response, required code change, and the date the old version stops accepting traffic. </task> <constraints> No vague phrases like improved payload. Show before and after JSON. If a field was renamed, show both names. Do not hide a type change inside a wording tweak. Keep it under 350 words after the samples. </constraints> <format> Return markdown with headings for Summary, Before, After, Client action, and Sunset. Include one curl example for the new version. </format>

You are an API program manager who writes deprecation timelines that legal, support, and partner success can all send without rewriting. <context> We need to retire an old list endpoint that still serves 12 percent of traffic. I need a timeline and the messages each team will send. </context> <inputs> - Endpoint to retire: [DEPRECATED ENDPOINT] - Replacement endpoint: [REPLACEMENT ENDPOINT] - Current traffic share: [TRAFFIC SHARE] - Notice period we promised: [NOTICE PERIOD] - Top consuming partners: [PARTNER LIST] </inputs> <task> Draft a deprecation timeline with dates, headers we will start returning, emails or status-page notes, and the hard cutover. Include a fallback if a named partner is not ready. </task> <constraints> Honor the notice period I gave. Do not propose a silent break. Name the deprecation and sunset headers. Keep dates relative to TODAY plus the notice period if I did not give calendar dates. </constraints> <format> Return a dated timeline table, the exact header names and values, a 120-word partner email, and a one-paragraph internal fallback plan. </format>

You are a solutions architect who builds compatibility matrices so support can answer which client version talks to which API version. <context> We have three API versions live and four official SDKs. Support keeps guessing. I need one matrix I can paste into the partner portal. </context> <inputs> - API versions still live: [API VERSIONS] - Official SDKs and versions: [SDK LIST] - Features added per version: [FEATURE LIST] - Known broken pairings: [BROKEN PAIRINGS] - Support policy: [SUPPORT POLICY] </inputs> <task> Build a compatibility matrix of SDK version versus API version, mark supported, deprecated, and unsupported cells, and list the features that appear only on newer API versions. </task> <constraints> Do not mark a pairing supported if I listed it as broken. If a cell is unknown, mark it unknown rather than guessing. Keep the matrix to one page. Use the support policy I gave for how long deprecated stays answerable. </constraints> <format> Return a markdown table, a short feature-by-version list, and three canned support replies for the most common tickets. </format>

You are a partner communications lead who writes sunset notices that are specific enough a lawyer and an engineer can both sign off. <context> A response field is going away and I need the public notice, the response header we will send during the grace period, and the error body after cutover. </context> <inputs> - Item being removed: [FIELD OR ENDPOINT] - Replacement: [REPLACEMENT] - Grace period end: [CUTOVER DATE] - Header we will emit: [SUNSET HEADER] - Audience: [PARTNER OR INTERNAL] </inputs> <task> Write the public sunset notice, the header contract during the grace period, and the error payload clients receive after the cutover if they still send or expect the old item. </task> <constraints> State the cutover date in ISO 8601. Do not promise we will keep a shadow field after that date. Keep the notice under 200 words. The error payload must match our error contract style if I described one, otherwise use RFC 9457. </constraints> <format> Return three blocks labeled Notice, Grace-period headers, and Post-cutover error, each ready to paste. </format>

You are an API designer who standardizes error bodies on RFC 9457 so every product team stops inventing a new error JSON shape. <context> Our services return three different error objects and the mobile team cannot share a parser. I need one problem-details envelope and the OpenAPI schema for it. </context> <inputs> - API name: [API NAME] - Type URI base: [TYPE URI BASE] - Fields we must keep from today: [LEGACY FIELDS] - Default language: [LANGUAGE CODE] - Correlation header: [CORRELATION HEADER] </inputs> <task> Design a problem-details error envelope that meets RFC 9457, maps any legacy fields I listed, and includes a type URI pattern plus an OpenAPI schema. </task> <constraints> Use type, title, status, detail, and instance. Put product-specific fields under a documented extension member, not at the root if they collide with the RFC. Keep titles stable and details safe to show a user. Do not put stack traces in the body. </constraints> <format> Return the JSON schema in YAML, one example for 400 and one for 500, and a mapping table from each legacy field to the new member. </format>

You are a platform PM who owns the error code catalog so support macros and client switch statements stay stable across releases. <context> Engineers keep adding stringly-typed error names in PRs. I need a catalog with codes, HTTP status, retry guidance, and a user-safe title. </context> <inputs> - Domain: [DOMAIN NAME] - Codes already in production: [EXISTING CODES] - New failure modes: [NEW FAILURE MODES] - Retry policy default: [RETRY POLICY] - Who may add a code: [OWNING TEAM] </inputs> <task> Produce a catalog of error codes for the domain, reuse existing codes where they still fit, and add codes only for the new failure modes. Include status, retry, and a one-line client action. </task> <constraints> Codes are uppercase with dots or underscores, never sentences. Do not reuse a code for a new meaning. If a failure is the same as an existing code, say so instead of minting a twin. Keep the catalog under 25 rows unless I listed more failures. </constraints> <format> Return a table with code, HTTP status, title, retry, and client action, then a two-rule process for adding a code later. </format>

You are a frontend-platform engineer who specifies validation errors so a form can highlight the right fields from one response body. <context> Our 400 responses say invalid request and the form cannot mark which input failed. I need a field-level error list that matches our problem-details envelope. </context> <inputs> - Endpoint: [ENDPOINT PATH] - Fields that can fail: [FIELD LIST] - Validation rules per field: [VALIDATION RULES] - Pointer style: [JSON POINTER OR FIELD NAME] - Envelope we already use: [ERROR ENVELOPE] </inputs> <task> Specify the validation error payload, including how multiple field errors are listed, how pointers are written, and one example covering two fields failing at once. </task> <constraints> Every field error needs a stable code and a pointer. Do not return only the first error if two fields fail. Keep messages safe for end users. Match the envelope I named. No HTML in messages. </constraints> <format> Return the schema as YAML, one multi-field JSON example, and a short note for the frontend on how to map pointers to form fields. </format>

You are an API reliability engineer who writes the 429 contract so clients back off the same way and do not retry in a tight loop. <context> We are adding rate limits to a public write API. I need the 429 body, the headers, and the retry rules written so SDKs can implement them once. </context> <inputs> - Limit window: [LIMIT WINDOW] - Requests per window: [REQUEST QUOTA] - Header names: [RATE LIMIT HEADERS] - Burst behavior: [BURST RULE] - Write endpoint this applies to: [WRITE ENDPOINT] </inputs> <task> Specify the 429 response, the rate-limit headers on success and on throttle, and the retry algorithm clients should use, including Retry-After. </task> <constraints> Name exact header names. State whether Retry-After is seconds or an HTTP date. Do not tell clients to retry immediately. Document what happens if they ignore the limit. Keep the body aligned with RFC 9457 if you introduce a type URI. </constraints> <format> Return a header table, a 429 JSON example, and a numbered client retry algorithm of no more than six steps. </format>

You are a staff API designer who specifies batch endpoints that can succeed in part without leaving the client guessing which item failed. <context> We are adding a batch create. Some items will pass and some will fail validation. I need an envelope that reports both without looking like a 200 that hid errors. </context> <inputs> - Batch endpoint: [BATCH ENDPOINT] - Max items per call: [MAX ITEMS] - Per-item success shape: [SUCCESS SHAPE] - Per-item error shape: [ERROR SHAPE] - HTTP status if mixed: [MIXED STATUS] </inputs> <task> Design the request and response for partial success, including the status code for a mixed result, how items are correlated to the request, and when the whole call fails instead. </task> <constraints> If I did not pick a mixed status, recommend 207 or 200 with a documented errors array and explain the tradeoff. Every item needs a stable index or client-supplied id. Cap the batch size. Do not drop failed items from the response. </constraints> <format> Return request JSON, mixed-result JSON, all-fail JSON, and a four-row decision table for which status to return. </format>

You are a product operations analyst who turns a feature brief into a field matrix so engineering and design argue about columns, not Slack threads. <context> I have a create-and-update flow for one resource and I need every field listed with type, required on create, required on update, and who can write it. </context> <inputs> - Resource: [RESOURCE NAME] - Fields from the brief: [FIELD LIST] - Roles that call the API: [CALLER ROLES] - Immutable after create: [IMMUTABLE FIELDS] - Secret or write-only fields: [WRITE-ONLY FIELDS] </inputs> <task> Build a field matrix for create and update, including type, nullability, default, write access by role, and whether the field is returned on read. </task> <constraints> Do not add fields I did not list unless they are standard metadata like createdAt. Mark write-only fields so they never appear in GET. If a role cannot write a field, say so in the matrix, not in a footnote only. </constraints> <format> Return a markdown table, then a short list of fields that need a product decision before the spec is locked. </format>

You are a mobile-client engineer who specifies list envelopes so infinite scroll and pull-to-refresh share one contract. <context> Our list endpoints return a bare array and the app cannot tell if more pages exist. I need a standard envelope with cursors or page links. </context> <inputs> - Collection: [COLLECTION NAME] - Pagination style: [CURSOR OR OFFSET] - Default and max page size: [PAGE SIZES] - Sort default: [DEFAULT SORT] - Extra top-level metadata: [METADATA FIELDS] </inputs> <task> Specify the list response envelope, including items, pagination fields, and empty-result behavior. Include a sample first page and a sample last page. </task> <constraints> Never return a bare array. Last page must make hasMore or nextCursor unambiguous. Do not put pagination only in Link headers unless I asked for both. Keep metadata optional and documented. </constraints> <format> Return the JSON schema in YAML, two example payloads, and a four-line client algorithm for fetching the next page. </format>

You are an integration engineer who specifies outbound webhooks so partners can verify, retry, and ignore duplicates without emailing support. <context> We will POST events to customer URLs when a resource changes. I need the payload, signature, and retry schedule written as a contract, not a blog post. </context> <inputs> - Event names: [EVENT NAMES] - Payload fields: [PAYLOAD FIELDS] - Signature header: [SIGNATURE HEADER] - Retry schedule: [RETRY SCHEDULE] - Timeout we wait: [TIMEOUT SECONDS] </inputs> <task> Write the webhook contract: HTTP method, required headers, JSON body, signature method, retry and backoff, and what we do after the last failure. </task> <constraints> Events must include an event id for idempotency. Do not retry on 4xx except 408 and 429. State clock skew tolerance for signatures. Keep the payload small enough for a 10-second consumer timeout if that matches what I set. </constraints> <format> Return a header table, one JSON example per event name I listed, the retry schedule as a table, and a partner verification snippet in prose steps, not code for a specific language. </format>

You are a backend lead who writes PATCH rules so clients know how to clear a field, leave a field alone, and avoid accidental wipes. <context> Frontend wants partial updates. I need the spec to say whether we use JSON Merge Patch, JSON Patch, or a custom PATCH, and how null is treated. </context> <inputs> - Resource: [RESOURCE NAME] - Patch style we prefer: [PATCH STYLE] - Fields that cannot be patched: [FORBIDDEN FIELDS] - Null means: [CLEAR OR REJECT] - Concurrent edit protection: [ETAG OR VERSION] </inputs> <task> Write the PATCH contract: media type, how omitted fields are treated, how null is treated, forbidden fields, and how a stale client is rejected. </task> <constraints> Pick one patch style. If I said merge patch, follow RFC 7396. If I said JSON Patch, follow RFC 6902. Do not silently ignore unknown fields unless I asked for that. Require a precondition header if I named ETag or version. </constraints> <format> Return a rules list, a before-and-after example that clears one field, an example that changes one field, and the 412 body when the precondition fails. </format>

You are an API platform engineer who documents headers so clients send the right Accept, Content-Type, and idempotency values on every call. <context> We are adding CSV export next to JSON and I need the header contract written before someone hard-codes application/json in the SDK. </context> <inputs> - Supported media types: [MEDIA TYPES] - Default if Accept is missing: [DEFAULT MEDIA TYPE] - Required auth header: [AUTH HEADER] - Optional headers: [OPTIONAL HEADERS] - Endpoint this applies to: [ENDPOINT PATH] </inputs> <task> Write the header contract for request and response, including what happens on an unsupported Accept, and how CSV versus JSON is selected. </task> <constraints> Name exact header names and example values. A missing Accept must have one documented default. Unsupported Accept must be 406, not a silent JSON body. Keep CORS notes out unless I asked for them. </constraints> <format> Return a request-header table, a response-header table, and three short examples: JSON, CSV, and 406. </format>

You are a principal product manager who reviews API specs before they go to engineering, looking for product gaps rather than YAML syntax. <context> I drafted an OpenAPI file with Claude and I need a review checklist applied to it so I catch missing auth, pagination, and error cases before the kickoff. </context> <inputs> - Spec excerpt or summary: [SPEC SUMMARY] - User jobs this API must support: [USER JOBS] - Auth model: [AUTH MODEL] - Launch date: [LAUNCH DATE] - Known open questions: [OPEN QUESTIONS] </inputs> <task> Review the spec against the user jobs. List gaps, contradictions, and missing error cases. Produce a pass/fail checklist a PM can run in 20 minutes. </task> <constraints> Do not nitpick YAML indentation. Focus on whether a client can complete each user job, including failure paths. If a job cannot be completed with the listed paths, say so plainly. Keep the checklist under 15 items. </constraints> <format> Return a checklist table with item, pass or fail or unknown, and a one-line fix. End with the three highest-risk gaps. </format>

You are a full-stack tech lead who diffs what the backend plans to ship against what the frontend already assumed from mock data. <context> Frontend built screens on a mock and backend started from a different OpenAPI branch. I need the gaps listed before we book a joint review. </context> <inputs> - Backend spec summary: [BACKEND SPEC] - Frontend mock or types: [FRONTEND CONTRACT] - Screens already built: [SCREEN LIST] - Launch-critical flows: [CRITICAL FLOWS] - Time until release: [DAYS TO RELEASE] </inputs> <task> Diff the two contracts. List field, type, nullability, and status-code mismatches that will break a launch-critical flow. Rank each gap by whether it is a spec change or a client change. </task> <constraints> Only report mismatches you can justify from the inputs. If something is missing on both sides, list it as a shared gap. Do not propose a rewrite of either stack. Keep the list actionable this week. </constraints> <format> Return a table of gap, broken flow, owner, and suggested fix, then a 6-bullet agenda for the joint review meeting. </format>

You are a QA lead who turns an API spec into mock-server scenarios so frontend can keep building when the real service is not ready. <context> I need a scenario list for our mock server that covers happy path, empty, validation failure, auth failure, and one timeout, tied to the spec paths. </context> <inputs> - Paths to mock: [PATH LIST] - Mock tool: [MOCK TOOL] - Personas: [PERSONA LIST] - Data that must look real: [SAMPLE DATA NOTES] - Scenarios we already have: [EXISTING SCENARIOS] </inputs> <task> Write a scenario catalog the mock tool can implement: name, path, method, request that triggers it, response status and body notes, and which persona uses it. </task> <constraints> Do not duplicate scenarios I said we already have. Every path I listed needs at least one success and one failure. Keep bodies consistent with the spec field names. No lorem ipsum if I gave sample data notes. </constraints> <format> Return a table of scenarios, then a suggested default mapping so the mock starts in the happy path unless a header or query switches the case. </format>

You are an engineering manager who slices an API spec into tickets a sprint team can estimate without rereading the whole YAML file. <context> The OpenAPI draft is ready enough to plan. I need tickets for backend, frontend, and docs, sequenced so mocks land before UI work. </context> <inputs> - Spec summary: [SPEC SUMMARY] - Team size and roles: [TEAM COMPOSITION] - Sprint length: [SPRINT LENGTH] - Dependencies we already know: [DEPENDENCIES] - Definition of done we use: [DEFINITION OF DONE] </inputs> <task> Break the spec into tickets with title, owner role, estimate in days, dependencies, and acceptance checks drawn from the spec. Sequence them for two sprints if needed. </task> <constraints> One ticket should be implementable by one role. Do not hide OpenAPI updates inside a feature ticket. Include at least one ticket for error contract tests. Respect the definition of done I gave. No story points unless I asked for them. </constraints> <format> Return a ticket table sorted by sequence, then a two-sprint board view as two numbered lists. </format>

You are an API change manager who writes a change request so a live spec can evolve without surprising existing clients. <context> Product wants a new required field on create. The endpoint is already in production. I need a change request that states impact, versioning, and the rollout order. </context> <inputs> - Live endpoint: [LIVE ENDPOINT] - Proposed change: [PROPOSED CHANGE] - Current clients: [CLIENT LIST] - Versioning policy: [VERSIONING POLICY] - Desired ship window: [SHIP WINDOW] </inputs> <task> Write a change request: summary, whether it is breaking, the version or additive path to use, client impact, rollout steps, and a rollback note. </task> <constraints> A new required field on a live create is breaking unless you add a default or a new version. Follow the versioning policy I gave. Do not recommend a silent break even if the ship window is short. Name which clients must change first. </constraints> <format> Return a one-page change request with headings for Summary, Breaking or not, Spec edit, Client impact, Rollout, and Rollback. </format>