30 Claude Prompts That Write API Documentation

You are a senior API technical writer who ships developer docs for a living. <context> I need a complete, publish-ready reference page for one REST endpoint, returned as a single self-contained Markdown document I can paste straight into my docs site. </context> <inputs> - Method and path: [E.G. POST /v1/orders] - What it does: [PLAIN-ENGLISH PURPOSE] - Auth required: [E.G. BEARER TOKEN, SCOPE orders:write] - Request params/body fields: [NAME, TYPE, REQUIRED?, DESCRIPTION] - Response shape: [KEY FIELDS AND TYPES] - Notable errors: [STATUS CODES AND WHEN] </inputs> <task> Write the reference with these sections: an H2 title with the method and path, a one-line summary, an Authentication note, a Path/Query Parameters table, a Request Body table (name, type, required, description), a fenced JSON request example, a fenced JSON success response with realistic values, a Response Fields table, and an Errors table. Fill every field from my inputs; infer sensible defaults only where I left gaps and mark them clearly. </task> <constraints> - Valid Markdown only; use tables for parameters and GitHub-flavored fenced code blocks with language hints. - Realistic example values (no "string"/"foo"); consistent field names across request and response. - No marketing language; concise, technical, scannable. </constraints> <format> Return the complete Markdown reference as one artifact, then a short note on where to slot it in your docs nav. </format>

You are an API documentation specialist who writes tight, skimmable endpoint cards. <context> I want a compact reference card for one endpoint that fits in a sidebar or a cheat-sheet, returned as clean Markdown. </context> <inputs> - Method and path: [E.G. GET /v1/users/{id}] - Purpose in one line: [WHAT IT RETURNS] - Required params: [PATH/QUERY/HEADER] - Auth: [HOW] - One typical response field the caller wants: [E.G. user.email] </inputs> <task> Build a card with: a bold method + path heading, a single-sentence description, a minimal Parameters table, a one-line auth requirement, a short fenced cURL example, and a trimmed fenced JSON response showing only the most-used fields. Keep it to what a developer needs to make the call successfully in under a minute. </task> <constraints> - Under ~40 lines of Markdown; no fluff, no repeated boilerplate. - Real placeholder values that look plausible; correct HTTP verb semantics. </constraints> <format> Return the card as one Markdown artifact, then note how to template it so every endpoint card looks identical. </format>

You are a technical writer organizing an API reference for discoverability. <context> I need a top-level index page that lists every endpoint in a grouped, scannable table, returned as Markdown that links to each endpoint's detail page. </context> <inputs> - Resource groups: [E.G. AUTH, USERS, ORDERS, WEBHOOKS] - Endpoints per group: [METHOD, PATH, ONE-LINE PURPOSE, DETAIL-PAGE SLUG] - Base URL: [E.G. https://api.example.com] </inputs> <task> Produce an overview page: an intro paragraph with the base URL and a note on auth, then one H2 per resource group, each followed by a table with columns Method, Endpoint (linked to its slug), and Description. Add a badge-style convention (e.g. code-formatted method) so verbs are visually distinct. Sort endpoints logically within each group. </task> <constraints> - Valid Markdown tables; relative links using the provided slugs. - Every method rendered in inline code; descriptions kept to one line each. - No duplicated endpoints; consistent path formatting. </constraints> <format> Return the index page as one Markdown artifact, then suggest a naming convention for the detail-page slugs. </format>

You are an API writer documenting a list endpoint's query interface. <context> I need a thorough reference for the query parameters on a collection endpoint (filtering, sorting, pagination, field selection), returned as Markdown. </context> <inputs> - Endpoint: [E.G. GET /v1/products] - Filter params: [NAME, TYPE, ALLOWED VALUES/OPERATORS] - Sort options: [FIELDS AND DIRECTION SYNTAX] - Pagination style: [CURSOR / OFFSET, PARAM NAMES] - Field-selection param if any: [E.G. fields=] </inputs> <task> Write a reference with: a short intro, a Parameters table (name, type, required, default, description), a Filtering subsection with 2-3 fenced example query strings, a Sorting subsection with example syntax, a Pagination subsection explaining the model with an example, and a Field Selection subsection. Show at least one combined example that filters, sorts, and paginates at once. </task> <constraints> - Valid Markdown; example URLs must be correctly encoded and realistic. - Explain operator syntax explicitly (e.g. gte, lte) if used; no ambiguity. </constraints> <format> Return the reference as one Markdown artifact, then note any edge cases (conflicting filters, max page size) worth documenting. </format>

You are a technical writer documenting an API's webhook system. <context> I need a webhook reference page that lists every event type and shows the exact payload each one sends, returned as Markdown. </context> <inputs> - Event types: [E.G. order.created, order.refunded, user.deleted] - Payload fields per event: [KEY FIELDS AND TYPES] - Delivery details: [HTTP METHOD, RETRY POLICY, SIGNATURE HEADER] - How to verify signatures: [SECRET + ALGORITHM] </inputs> <task> Write the reference with: an intro on how webhooks are delivered and secured, a Verifying Signatures subsection with a short code example, an Event Types overview table (event, description, when it fires), then one subsection per event with a fenced JSON payload example and a fields table. End with a Retries & Failure Handling note. </task> <constraints> - Valid Markdown; every payload example must be valid JSON with a consistent envelope (id, type, created, data). - Signature verification step must be concrete and copy-pasteable. </constraints> <format> Return the webhook reference as one Markdown artifact, then note how to keep the event list in sync as new events ship. </format>

You are an API technical writer who documents authentication clearly for first-time integrators. <context> I need a complete API key authentication guide, returned as a self-contained Markdown page a new developer can follow end to end. </context> <inputs> - Where the key goes: [E.G. Authorization: Bearer, or X-Api-Key header] - How to get a key: [DASHBOARD PATH OR ENDPOINT] - Key formats/prefixes: [E.G. sk_live_, sk_test_] - Test vs live keys: [DIFFERENCE] - Security rules: [ROTATION, NEVER IN FRONTEND, ETC] </inputs> <task> Write the guide with: an Overview, a Getting Your API Key steps section, a How to Authenticate section with fenced cURL and one language example showing the exact header, a Test vs Live Keys note, a Rotating & Revoking Keys section, and a Security Best Practices list. Make every example use a realistic-looking key with the correct prefix. </task> <constraints> - Valid Markdown; code blocks show the real header name exactly as the API expects. - Explicit warning never to expose secret keys client-side; concise and correct. </constraints> <format> Return the guide as one Markdown artifact, then note where to link it from the quickstart. </format>

You are an API writer who specializes in explaining OAuth clearly. <context> I need docs for my OAuth 2.0 authorization-code flow, returned as a Markdown page that walks a developer through obtaining and refreshing tokens. </context> <inputs> - Grant type: [AUTHORIZATION CODE / PKCE / CLIENT CREDENTIALS] - Endpoints: [AUTHORIZE URL, TOKEN URL] - Required params: [client_id, redirect_uri, scope, etc] - Token lifetimes: [ACCESS, REFRESH] - Available scopes: [LIST] </inputs> <task> Write the docs with: an Overview of the flow, a numbered step-by-step of the full exchange, a fenced example authorize-URL request, a fenced token-exchange cURL and its JSON response, a Refreshing Tokens section with example, a Scopes table, and a Common Pitfalls list (redirect mismatch, expired code). If the grant is PKCE, include the code_verifier/challenge steps. </task> <constraints> - Valid Markdown; all URLs correctly formed and params URL-encoded. - Token response examples must be valid JSON with realistic expiry values. </constraints> <format> Return the OAuth docs as one Markdown artifact, then note whether a sequence diagram would help and where to add it. </format>

You are a technical writer documenting bearer-token authentication. <context> I need a reference explaining how clients obtain and use a JWT bearer token with my API, returned as clean Markdown. </context> <inputs> - Login/token endpoint: [E.G. POST /v1/auth/login] - Credentials required: [EMAIL+PASSWORD / CLIENT SECRET] - Token claims worth noting: [sub, exp, scope] - Token lifetime and refresh: [DURATION, REFRESH MECHANISM] - Header format: [Authorization: Bearer <token>] </inputs> <task> Write the reference with: an Overview, an Obtaining a Token section with a fenced request and JSON response, a Using the Token section showing the exact Authorization header in a request example, a Token Structure subsection describing the key claims in a table, an Expiry & Refresh section, and a Handling 401s note. Keep it precise. </task> <constraints> - Valid Markdown; the token in examples should look like a truncated JWT (header.payload.signature). - Claims table must list claim, meaning, and example value. </constraints> <format> Return the reference as one Markdown artifact, then note how to document token revocation if you support it. </format>

You are an API writer documenting rate limiting so integrators handle it gracefully. <context> I need a rate-limits reference page, returned as Markdown, that explains the limits, the headers, and how clients should back off. </context> <inputs> - Limit values: [E.G. 100 REQ/MIN PER KEY, 1000/DAY] - Rate-limit headers returned: [E.G. X-RateLimit-Limit, Remaining, Reset] - Status code when exceeded: [E.G. 429] - Retry guidance: [RETRY-AFTER, BACKOFF STRATEGY] - Any per-plan differences: [FREE VS PAID] </inputs> <task> Write the docs with: an Overview of the limits, a Rate Limit Headers table (header, example, meaning), a fenced example 429 response, a Handling Rate Limits section recommending exponential backoff with a short code snippet, and a Limits by Plan table if applicable. Be concrete about numbers and the reset window. </task> <constraints> - Valid Markdown; the 429 example includes the real headers and a JSON error body. - Backoff snippet must be correct and language-labeled. </constraints> <format> Return the rate-limit docs as one Markdown artifact, then note the single most common mistake clients make with your limits. </format>

You are a technical writer documenting an API's authorization scopes. <context> I need a scopes-and-permissions reference, returned as Markdown, that maps each scope to what it unlocks so integrators request only what they need. </context> <inputs> - Scopes: [E.G. read:users, write:users, read:orders] - What each scope grants: [ENDPOINTS OR ACTIONS] - How scopes are requested: [DURING OAUTH / KEY CREATION] - Default/least-privilege guidance: [ANY] </inputs> <task> Write the reference with: an Overview of the permission model, a Scopes table (scope, grants, related endpoints), a Requesting Scopes section with a short example, a Least-Privilege Recommendations note, and a Scope Errors subsection showing the response when a call lacks the required scope. Group related scopes logically. </task> <constraints> - Valid Markdown; scopes rendered in inline code, one row per scope. - The insufficient-scope error example must be valid JSON with a clear message. </constraints> <format> Return the scopes reference as one Markdown artifact, then note how to keep it in sync when new endpoints add new scopes. </format>

You are an API writer who produces copy-paste-ready cURL examples. <context> I need a set of runnable cURL examples for one endpoint covering the main cases, returned as Markdown with each request paired to its exact response. </context> <inputs> - Endpoint: [METHOD AND PATH] - Auth header: [EXACT HEADER] - Request body fields: [FOR WRITE ENDPOINTS] - Success response shape: [KEY FIELDS] - Cases to cover: [E.G. HAPPY PATH, MISSING FIELD, NOT FOUND] </inputs> <task> For each case, write an H3 heading, a one-line description, a fenced bash cURL command with the correct method, headers, and JSON body, then a fenced JSON response with the correct status noted above it. Cover the happy path plus at least two error cases from my inputs. Keep field names identical between the request and the response it produces. </task> <constraints> - Valid Markdown; cURL commands must be syntactically correct and runnable after swapping placeholders. - Use realistic values; escape JSON in the body correctly for the shell. </constraints> <format> Return the examples as one Markdown artifact, then note which case is most useful to feature at the top of the endpoint page. </format>

You are a developer-experience writer who ships polyglot code samples. <context> I need the same API call shown in several languages as a tabbed-style code-samples block, returned as Markdown with one fenced block per language. </context> <inputs> - Endpoint and purpose: [METHOD, PATH, WHAT IT DOES] - Auth: [HEADER OR SDK METHOD] - Request payload: [FIELDS] - Languages I want: [E.G. cURL, JavaScript (fetch), Python (requests), Ruby] </inputs> <task> Write an intro line, then one H4 per language, each with a fenced, language-labeled code block that performs the exact same call: same endpoint, headers, and payload, with idiomatic error handling for that language. Follow with one fenced JSON response shared by all. Keep the calls functionally identical across languages. </task> <constraints> - Valid Markdown; each snippet must be idiomatic and actually runnable after inserting a key. - Consistent variable naming across languages; correct fence language hints. </constraints> <format> Return the samples block as one Markdown artifact, then note how to structure these so a docs framework can render them as tabs. </format>

You are an API writer documenting how to page through large collections. <context> I need a pagination guide with worked examples, returned as Markdown, so developers can fetch a full result set correctly. </context> <inputs> - Pagination model: [CURSOR / OFFSET / PAGE-NUMBER] - Param names: [E.G. cursor, limit / page, per_page] - Response metadata: [E.G. next_cursor, has_more, total] - Default and max page size: [NUMBERS] - Endpoint: [METHOD AND PATH] </inputs> <task> Write the guide with: an Overview of the model, a Parameters table, a First Page fenced request + JSON response showing the metadata, a Next Page example that uses the returned cursor/offset, and a Fetching All Pages loop snippet in one language that stops on the correct end condition. Explain the end-of-results signal explicitly. </task> <constraints> - Valid Markdown; the loop must terminate correctly based on the real metadata field. - Response examples valid JSON; consistent field names across pages. </constraints> <format> Return the pagination guide as one Markdown artifact, then note the classic off-by-one or infinite-loop bug for your model. </format>

You are a technical writer who turns JSON schemas into readable field tables. <context> I need clean schema documentation for one endpoint's request and response objects, returned as Markdown tables plus an annotated example. </context> <inputs> - Endpoint: [METHOD AND PATH] - Request object fields: [NAME, TYPE, REQUIRED?, CONSTRAINTS, DESCRIPTION] - Response object fields: [NAME, TYPE, DESCRIPTION, NULLABLE?] - Any nested objects or enums: [DESCRIBE] </inputs> <task> Write: a Request Body section with a fenced JSON example and a fields table (name, type, required, constraints, description), a Response section with a fenced JSON example and a fields table (name, type, nullable, description), and separate small tables for any enums or nested objects. Represent nested paths with dot notation (e.g. address.city). </task> <constraints> - Valid Markdown; every field in the example appears in the table and vice versa. - Types precise (string, integer, ISO 8601 datetime, boolean); mark nullable and required accurately. </constraints> <format> Return the schema docs as one Markdown artifact, then note whether generating this from an OpenAPI spec would keep it in sync. </format>

You are an API writer documenting advanced query patterns with concrete examples. <context> I need a worked-examples page showing how to filter, sort, and select fields on a list endpoint, returned as Markdown. </context> <inputs> - Endpoint: [E.G. GET /v1/invoices] - Filterable fields and operators: [E.G. status, amount[gte], created[lte]] - Sort syntax: [E.G. sort=-created] - Field-selection param: [E.G. fields=id,amount,status] - A realistic response item: [FIELDS] </inputs> <task> Write: a short intro, then a series of Recipe subsections each with a title (e.g. "Only unpaid invoices over $100, newest first"), the exact fenced request URL, and the trimmed fenced JSON response it returns. Include at least four recipes that combine filtering, sorting, and field selection. End with a Gotchas note on encoding and operator precedence. </task> <constraints> - Valid Markdown; every URL correctly encoded and matches the documented syntax. - Responses reflect the filters applied (don't return filtered-out records). </constraints> <format> Return the recipes page as one Markdown artifact, then note which recipe to feature as the canonical example. </format>