Your API is only as good as its documentation. The best-designed endpoints become useless if developers cannot figure out how to call them. Yet API docs are often an afterthought: incomplete, outdated, or written so tersely that developers spend more time guessing than building.
Great API documentation does three things: it gets developers to “Hello World” in under five minutes, it answers every question they will have during integration, and it stays current as your API evolves. This guide gives you prompt templates to achieve all three.
Document my REST API endpoints.
Write API documentation for our user management endpoints.
CONTEXT:
- REST API built with Node.js and Express
- Base URL: https://api.example.com/v1
- Authentication: Bearer token (JWT)
- Target audience: Frontend developers integrating our user system
ENDPOINTS TO DOCUMENT:
- POST /users (create user)
- GET /users/{id} (get user by ID)
- PATCH /users/{id} (update user)
- DELETE /users/{id} (delete user)
FOR EACH ENDPOINT INCLUDE:
1. HTTP method and path with description
2. Authentication requirements
3. Request parameters (path, query, body) with types
4. Response schema for success (200/201)
5. Error responses (400, 401, 403, 404, 422)
6. cURL example with a working request
7. JavaScript fetch example
8. Rate limiting notes
FORMAT: Markdown with proper code blocks and tablesAnatomy of Great API Docs
Before diving into prompts, understand what separates documentation developers love from documentation they dread.
Quick start that actually works
A single page that takes developers from zero to first successful API call. Include copy-paste code, test credentials if possible, and expected output.
Complete endpoint reference
Every endpoint documented consistently. Same structure, same level of detail. Developers should be able to predict where to find information.
Real examples, not schemas alone
JSON schemas are necessary but not sufficient. Include actual request and response examples that developers can copy and modify.
Error handling guidance
Document every error code, what triggers it, and how to fix it. Developers will spend more time debugging than happy-path coding.
The ENDPOINT Framework
Use this framework to structure prompts for consistent, complete API documentation. Each letter represents a section every endpoint doc needs.
Endpoint path
Notes and description
Data formats
Parameters
Output examples
Intro to authentication
Nuances and edge cases
Testing and debugging
Insight
Endpoint Reference
The core of API documentation. This prompt template generates complete documentation for a single endpoint.
Write documentation for this API endpoint. ENDPOINT: [METHOD] [PATH] Example: POST /api/v1/orders API CONTEXT: - API type: [REST, GraphQL, gRPC] - Base URL: [production base URL] - Authentication: [Bearer token, API key, OAuth 2.0] - Content-Type: [application/json, multipart/form-data] ENDPOINT DETAILS: - Purpose: [what this endpoint does in one sentence] - When to use: [common use cases] - Related endpoints: [list any related endpoints] REQUEST SCHEMA: [paste TypeScript interface, JSON Schema, or example request body] RESPONSE SCHEMA: [paste TypeScript interface, JSON Schema, or example response] DOCUMENT THESE SECTIONS: 1. **Overview** - HTTP method and full path - One-paragraph description - Authentication requirements 2. **Request** - Path parameters (name, type, description, required) - Query parameters (name, type, description, default, required) - Request headers (beyond standard auth) - Request body schema with field descriptions 3. **Response** - Success response (status code, schema, example) - Error responses (each error code with cause and example) 4. **Examples** - cURL command (with placeholder values) - JavaScript/TypeScript fetch example - Python requests example 5. **Notes** - Rate limiting - Pagination (if applicable) - Idempotency - Known limitations FORMAT: Markdown with code blocks using appropriate syntax highlighting
Pro Tip
Authentication Guide
Authentication is where developers get stuck first. A clear auth guide unblocks them before they even read the endpoint docs.
Write an authentication guide for our API. AUTHENTICATION METHOD: [Choose one or more] - API Key (header or query param) - Bearer Token (JWT) - OAuth 2.0 (which flows?) - Basic Auth API CONTEXT: - Base URL: [your API base URL] - Environment: [sandbox/production URLs if different] - Token expiry: [how long tokens last] - Refresh mechanism: [how to get new tokens] GUIDE STRUCTURE: 1. **Overview** - Which auth method(s) we support - When to use each (if multiple) - Security best practices 2. **Getting Credentials** - Where to find/generate API keys or client IDs - Step-by-step with screenshots if helpful - Sandbox vs production credentials 3. **Making Authenticated Requests** - Header format (exact header name and value format) - Query param format (if applicable) - Example request with auth 4. **Token Lifecycle** (for token-based auth) - How to obtain tokens (endpoint, request format) - Token expiration and refresh flow - Handling expired tokens gracefully 5. **Error Handling** - 401 Unauthorized scenarios - 403 Forbidden scenarios - How to debug auth issues 6. **Code Examples** - cURL with auth header - JavaScript/TypeScript - Python - Include token refresh flow if applicable 7. **Security Recommendations** - Never commit credentials - Use environment variables - Rotate keys periodically - Minimum required scopes FORMAT: Markdown with clear headings and code examples
Request and Response Examples
Examples are the most-copied part of API docs. Make them complete, realistic, and copy-paste ready.
Generate request/response examples for this API endpoint. ENDPOINT: [METHOD] [PATH] Example: POST /api/v1/users CONTEXT: - This endpoint: [brief description] - Required fields: [list them] - Optional fields: [list them with defaults] GENERATE EXAMPLES FOR: 1. **Minimal Request** (only required fields) - cURL command - Request body - Expected response 2. **Full Request** (all fields populated) - cURL command - Request body with all options - Expected response 3. **Common Variations** - [Specific use case 1, e.g., "creating admin user"] - [Specific use case 2, e.g., "user with custom metadata"] 4. **Error Scenarios** - Missing required field (show request and 400 response) - Invalid field value (show request and 422 response) - Unauthorized (show request and 401 response) - Resource not found (show request and 404 response) - Rate limited (show 429 response) REQUIREMENTS: - Use realistic but fake data (no real emails/names) - Include all response fields, not truncated - Show exact status codes - Include response headers if relevant (pagination, rate limit)
- Complete: Full request and response, not truncated with “...”
- Realistic: Fake data that looks real (proper UUIDs, valid emails)
- Runnable: cURL commands should work if you replace the token
- Consistent: IDs in request match IDs in response
- Timestamped: Use ISO 8601 dates that make sense
Error Codes
Error documentation is debugging documentation. Every error should tell developers exactly what went wrong and how to fix it.
Create an error code reference for our API. API CONTEXT: - Error format: [JSON structure of your error responses] - Error code pattern: [e.g., ERR_xxx, numeric codes, HTTP status only] DOCUMENT THESE ERROR CATEGORIES: 1. **Client Errors (4xx)** - 400 Bad Request (malformed JSON, missing fields) - 401 Unauthorized (invalid/missing auth) - 403 Forbidden (valid auth, insufficient permissions) - 404 Not Found (resource does not exist) - 409 Conflict (duplicate resource, state conflict) - 422 Unprocessable Entity (validation failures) - 429 Too Many Requests (rate limited) 2. **Server Errors (5xx)** - 500 Internal Server Error - 502 Bad Gateway - 503 Service Unavailable - 504 Gateway Timeout FOR EACH ERROR INCLUDE: - HTTP status code - Error code (if you use custom codes) - Error message example - What causes this error (be specific) - How to fix it (actionable steps) - Example error response JSON ALSO INCLUDE: - Error response schema/structure - How to parse error responses in code - Retry logic recommendations - When to contact support vs self-debug FORMAT: Markdown with tables and code blocks
Warning
Rate Limiting
Rate limits are a common source of production issues. Clear documentation prevents support tickets and frustrated developers.
Write rate limiting documentation for our API. RATE LIMIT DETAILS: - Limit type: [requests per second, per minute, per day] - Limit values: [e.g., 100 requests/minute for free tier] - Scope: [per API key, per user, per IP, per endpoint] - Tier differences: [if limits vary by plan] RATE LIMIT HEADERS: - X-RateLimit-Limit: [what it means] - X-RateLimit-Remaining: [what it means] - X-RateLimit-Reset: [format: Unix timestamp, seconds until reset, etc.] - Retry-After: [when returned] DOCUMENT: 1. **Overview** - What limits apply and why - How limits are calculated - Different limits by endpoint (if applicable) 2. **Rate Limit Headers** - Each header with description - Example response showing all headers - How to parse the reset time 3. **When You Hit the Limit** - 429 response format - Retry-After header usage - Backoff strategy recommendation 4. **Best Practices** - Implement exponential backoff - Cache responses when possible - Batch requests where supported - Monitor your usage 5. **Code Examples** - Reading rate limit headers - Implementing retry with backoff - Preemptive rate limit checking 6. **Increasing Limits** - How to request higher limits - Enterprise/custom plans FORMAT: Markdown with code examples in JavaScript and Python
SDK Quickstart
If you provide SDKs, developers want to use them. A quickstart guide should get them from installation to first API call in five minutes.
Write an SDK quickstart guide. SDK DETAILS: - Language: [JavaScript/TypeScript, Python, Go, etc.] - Package name: [npm package, PyPI package, etc.] - Package manager: [npm, yarn, pip, etc.] - Minimum runtime version: [Node 18+, Python 3.9+, etc.] API CONTEXT: - What the API does: [one sentence] - Most common first action: [e.g., "list users", "create record"] - Authentication method: [API key, OAuth, etc.] QUICKSTART STRUCTURE: 1. **Installation** - Package manager command - Verify installation 2. **Configuration** - Initialize the client - Set API key/credentials - Configure options (timeout, retry, etc.) 3. **First API Call** - Simplest possible example - Expected output - What to do if it fails 4. **Common Operations** - Create (example with explanation) - Read (example with explanation) - Update (example with explanation) - Delete (example with explanation) 5. **Error Handling** - Try/catch pattern - Accessing error details - Common errors and fixes 6. **Next Steps** - Link to full SDK reference - Link to API reference - Example projects REQUIREMENTS: - Every code example must be complete and runnable - Use async/await for JavaScript - Include type hints for Python - Show expected console output
REST vs GraphQL Documentation
REST and GraphQL require different documentation approaches. Here is how to adapt your prompts for each.
REST API Documentation
- Document each endpoint separately
- HTTP methods are central (GET, POST, PUT, DELETE)
- Fixed response shapes per endpoint
- Versioning in URL or header
- Focus on resource-oriented design
GraphQL Documentation
- Document types, queries, and mutations
- Single endpoint, flexible queries
- Client controls response shape
- Schema is self-documenting (use descriptions)
- Focus on field-level documentation
Write documentation for this GraphQL operation. OPERATION TYPE: [Query | Mutation | Subscription] OPERATION NAME: [e.g., getUser, createOrder] SCHEMA: [paste the relevant type definitions] DOCUMENT: 1. Operation description 2. Arguments with types and descriptions 3. Return type with field descriptions 4. Example query/mutation 5. Example variables 6. Example response 7. Error scenarios 8. Related operations Include introspection-friendly descriptions that will appear in GraphQL playground.
Versioning and Changelogs
APIs evolve. Version documentation and changelogs help developers upgrade smoothly.
Write a changelog entry for API version [X.Y.Z]. VERSION DETAILS: - Version number: [e.g., v2.1.0] - Release date: [date] - Previous version: [e.g., v2.0.0] CHANGES IN THIS VERSION: New Features: - [Feature 1 description] - [Feature 2 description] Breaking Changes: - [Breaking change 1] - [Breaking change 2] Deprecations: - [What is deprecated and when it will be removed] Bug Fixes: - [Fix 1] - [Fix 2] DOCUMENT FOR EACH CHANGE: 1. What changed (before → after) 2. Why it changed 3. Migration steps (for breaking changes) 4. Code example showing old vs new FORMAT: - Use semantic versioning terminology - Mark breaking changes prominently - Include migration guide for major versions - Link to relevant endpoint documentation
Insight
Interactive API Explorers
Static docs tell developers what to do. Interactive explorers let them try it. Use AI to generate the specifications that power these tools.
Generate an OpenAPI 3.0 specification for this endpoint. ENDPOINT: [METHOD] [PATH] ENDPOINT DETAILS: - Summary: [brief description] - Description: [detailed explanation] - Tags: [category tags for grouping] REQUEST: - Path parameters: [list with types] - Query parameters: [list with types and defaults] - Request body: [paste schema or TypeScript interface] RESPONSES: - 200/201: [success response schema] - 400: [bad request schema] - 401: [unauthorized schema] - 404: [not found schema] - 422: [validation error schema] SECURITY: - Authentication: [Bearer, ApiKey, OAuth2] - Required scopes: [if OAuth] GENERATE: - Complete OpenAPI 3.0 YAML for this endpoint - Include examples for request and all responses - Add descriptions to all fields - Use $ref for reusable schemas - Include operationId for SDK generation OUTPUT: Valid OpenAPI 3.0 YAML
Swagger UI / ReDoc
Use OpenAPI specs to generate interactive documentation. Developers can try endpoints directly from the browser.
Postman Collections
Generate Postman collections from your specs. Developers can import and start testing immediately.
GraphQL Playground
For GraphQL APIs, the schema is the spec. Add descriptions to types and fields - they appear in the explorer.
Next Steps
You have the frameworks and templates. AskSmarter.ai helps you apply them by asking the right questions about your API, your audience, and your endpoints to generate documentation that developers will actually use.
Generate your API documentation now
Answer questions about your API endpoints, authentication, and target developers. AskSmarter creates prompts that produce clear, complete API docs that reduce integration time and support tickets.
Start documenting your API