Coding
AI Prompt for Endpoint Documentation
Document any REST endpoint perfectly with this AI prompt: parameter tables, copy-pasteable examples, every error case, and caller action guidance.
The prompt
Role: You are a technical writer documenting one API endpoint exhaustively. Context: Endpoint: [METHOD] [PATH]. Purpose: [PURPOSE]. Parameters: [PARAMETERS: name, location, type, required, description] Success response: [SUCCESS_RESPONSE: status code + body shape] Error cases: [ERROR_CASES: status code + when it happens] Task: Write the endpoint documentation with: 1) One-paragraph description of what it does and when to use it. 2) Parameter table (name, in, type, required, default, description). 3) Full request example with realistic data. 4) Full success response example. 5) Each error case with status code, example body, and what the caller should do. 6) Notes: idempotency, rate limits, and gotchas. Format: Use exactly these sections in order: Overview, Parameters, Request Example, Response Example, Errors, Notes. Ask the AI to include a version-history note for the endpoint: what changed in each version and the migration path. Endpoint docs without history force integrators to guess. Constraints: Examples must be complete and copy-pasteable — no "..." placeholders. Every documented error must have the caller's next action, not just the code.
Variables to fill in
Replace each [variable] in the prompt with your own details:
[METHOD] [PATH] [PURPOSE] [PARAMETERS] [SUCCESS_RESPONSE] [ERROR_CASES]
Example input
ENDPOINT=POST /api/v1/orders, PURPOSE=create a new order, PARAMS=customer_id (path), items array, coupon_code optional, ERRORS=400 invalid items, 404 customer not found, 409 duplicate order
How to use this prompt
Fill in the error cases from your actual code — invented error docs mislead integrators. Include one realistic full example; developers copy-paste it first.
Tips for the best results
- Write the caller's next action for every error — 'what do I do now' is what developers need.
- Include the idempotency behavior; integrators always ask about retries.
- Ask the AI to draft the changelog entry when the endpoint changes later.
Frequently asked questions
How is this different from full API docs?
This prompt goes deep on one endpoint (examples, errors, edge cases); the full-docs prompt covers the whole API shallowly. Use both.
How detailed should error documentation be?
Every error needs the status code, an example body, and the caller's next action. 'What do I do now' is the question developers actually ask.