Write implementation-ready API documentation from the materials below. API and endpoint purpose: [ENDPOINT PURPOSE] Authoritative technical inputs: [TECHNICAL SOURCE MATERIAL] Authentication and authorization rules: [AUTH RULES] Request and response examples or schemas: [SCHEMAS AND EXAMPLES] Intended developer audience and language examples: [AUDIENCE AND LANGUAGES] Treat the supplied materials as the source of truth. Do not invent routes, parameters, headers, enum values, limits, SDK methods, error codes, guarantees, or response fields. If the materials conflict, identify the conflict instead of choosing silently. If a behavior is absent, mark it “not specified.” Produce documentation in Markdown with these sections: 1. One-paragraph overview stating what the endpoint does, its main use case, and any important side effect. 2. Endpoint reference: HTTP method, path, authentication requirement, required scopes or roles, idempotency behavior, content type, and rate-limit information if supplied. 3. Request: parameter table with name, location, type, required status, validation rules, default, and description. Include a complete valid example in each requested language. 4. Response: success status code, field table with type and nullability, and a formatted example. Explain pagination, asynchronous processing, or eventual consistency only when documented. 5. Errors: a table covering each documented status code, machine-readable error field, likely cause, and caller action. Include validation and authorization failures separately. 6. Integration notes: retries, timeouts, ordering, webhooks, security handling, and migration concerns only where supported by the inputs. Finish with “Open questions / missing specification” listing every gap that would prevent a safe implementation. Before answering, check that all examples match the schema and that every stated behavior is traceable to [TECHNICAL SOURCE MATERIAL] or the supplied schemas. Ask up to 3 clarifying questions only if a required input is missing.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [ENDPOINT PURPOSE] | State the endpoint’s purpose, business action, and any known side effects. | Create a payout request for an approved marketplace seller; the request is queued for asynchronous processing. |
| [TECHNICAL SOURCE MATERIAL] | Paste code, OpenAPI fragments, tickets, design notes, or verified engineering details. | POST /v1/payouts accepts seller_id, amount_cents, currency, and idempotency_key. It returns 202 with a payout object. Amount must be 100-500000 cents. Processing status changes through a webhook. |
| [AUTH RULES] | Describe the authentication method, scopes, roles, and authorization constraints. | Bearer API key with payouts:write scope; keys may create payouts only for sellers in their organization. |
| [SCHEMAS AND EXAMPLES] | Provide request and response schemas plus any real or representative examples. | Request: seller_id string, amount_cents integer, currency enum USD|CAD, idempotency_key UUID. Response: id, status queued|paid|failed, created_at ISO 8601. |
| [AUDIENCE AND LANGUAGES] | State who will use the documentation and which code languages need examples. | Third-party backend developers; cURL and Node.js examples. |
How to use
- Paste an OpenAPI fragment or code-level contract alongside product notes; prose alone often omits validation and lifecycle details.
- Make missing states visible before publishing, especially authorization behavior, idempotency, async completion, and error payloads.
- Run each generated example against a validator, test environment, or contract test before treating it as documentation.
- Follow up with: “Convert the missing-specification list into questions for the API owner, grouped by implementation risk.”
Variations
OpenAPI draft
Use this when you need a contract draft from confirmed endpoint behavior.
Draft an OpenAPI 3.1 YAML definition for [ENDPOINT]. Confirmed behavior: [TECHNICAL FACTS]. Shared component schemas available: [COMPONENT SCHEMAS]. Produce only valid YAML for the path, operation, parameters, request body, responses, security, and documented error schemas. Use descriptions to clarify validation and lifecycle behavior. Do not infer fields, response codes, or formats absent from the facts. Before answering, check YAML indentation and ensure every example conforms to its declared schema; list unresolved contract gaps after the YAML.
Quickstart guide
Use this when developers need to complete one common workflow quickly.
Write a quickstart for developers who need to [USER GOAL] with [API OR SDK]. Verified prerequisites and authentication: [PREREQUISITES]. Confirmed sequence of calls: [WORKFLOW FACTS]. Languages: [LANGUAGES]. Produce a 700-word guide with setup, a minimal end-to-end code example, expected output, verification steps, and cleanup or rollback notes if applicable. Keep advanced options out of the main path. Do not create credentials, endpoints, or SDK methods. Before answering, check that a new developer can follow each step using only supplied facts.
Error reference
Use this when integration support is receiving repeated API error questions.
Create an API error-handling reference for [API AREA]. Documented errors and payloads: [ERROR MATERIAL]. Caller context: [CLIENT TYPE]. Produce a table with HTTP status, error code, trigger, whether retrying is appropriate, safe retry behavior, and an example handler in [LANGUAGE]. Separate client mistakes, authorization failures, conflicts, and transient service failures. Do not say an error is retryable without evidence. Before answering, check that every handler preserves error details for diagnosis and does not retry non-idempotent operations blindly.
Tips
- Document the successful request and response, then document what happens when the same request is repeated, unauthorized, malformed, or delayed.
- A code sample should be executable in principle: include required headers, real field shapes, and response handling rather than placeholders that hide the hard part.
- Keep API reference facts separate from workflow guidance; a field table answers “what exists,” while a quickstart explains “what to do first.”
- Mark undocumented behavior as unspecified instead of making it sound stable, particularly around ordering, retries, and eventual consistency.
FAQ
Can AI write API docs from code?
It can turn code and schemas into a useful draft, but it may miss runtime behavior, authorization policy, and operational limits. Supply tests, OpenAPI contracts, and owner notes where possible.
Should API documentation include error examples?
Yes. A caller needs to know the status code, machine-readable fields, likely cause, and safe corrective action.
How do I keep generated docs from drifting from the API?
Generate or validate reference sections from an API contract in CI, and assign ownership for behavioral notes that the contract cannot express.