This API docs prompt turns endpoint code into publishable developer docs
Why this prompt matters
Undocumented endpoints slow down every team that touches them. Engineers waste time reading handlers, support teams answer the same integration questions repeatedly, and partner launches slip because nobody is fully sure which fields are required or what errors to expect. A prompt like this turns documentation from an afterthought into a release artifact.
What we use it for
Use this prompt when you are shipping or reviewing an API endpoint and the docs are lagging behind the code. It is especially useful when a backend engineer needs to turn a route handler, schema, and a few response examples into publishable docs before a release, SDK handoff, or partner integration.
Prompt
Role: Act as a senior API technical writer and backend engineer who documents production endpoints for developer platforms. Context: I will give you one or more API endpoint handlers, route definitions, validation schemas, example responses, and optional business context. The code may be incomplete, spread across files, or mixed with framework boilerplate. Task: Produce accurate, developer-facing API documentation that another engineer can use without reading the original code first. Constraints: - Use only behavior supported by the code or by clearly labeled assumptions. - Do not invent parameters, status codes, auth rules, rate limits, or side effects that are not shown. - If the code is ambiguous, create an "Open questions" section instead of guessing. - Keep naming consistent with the source code. - Prefer concrete examples over abstract explanations. - Call out risky gaps such as missing validation, undocumented error paths, or unclear auth behavior. Output Format: 1. Endpoint Summary - Method: [HTTP METHOD] - Path: [ENDPOINT PATH] - Purpose: one paragraph 2. Authentication and Permissions 3. Request Details - Path parameters - Query parameters - Headers - Request body schema - Validation rules 4. Response Details - Success response with JSON example - Error responses with likely causes 5. Business Logic Notes - Important side effects - Derived fields or hidden rules 6. Edge Cases and Limitations 7. Open Questions 8. Ready-to-publish docs block in clean Markdown Input to use: - Framework/language: [FRAMEWORK OR LANGUAGE] - Route definition(s): [PASTE ROUTE CODE] - Handler/service code: [PASTE HANDLER OR SERVICE CODE] - Validation schema: [PASTE SCHEMA OR "none"] - Example request/response: [PASTE EXAMPLES OR "none"] - Business context: [OPTIONAL CONTEXT OR "none"]
Result
Endpoint Summary - Method: POST - Path: /v1/projects/{projectId}/invites - Purpose: Creates a pending workspace invite for a new team member and optionally sends an email invitation. This endpoint is intended for project admins who need to grant access without manually provisioning users in the dashboard. The code shows that the invite is tied to a specific project, stores the target email in normalized lowercase form, and rejects duplicate active invites for the same address.
Authentication and Permissions The route is protected by `requireSession()` and then checks `assertProjectRole(projectId, user.id, ['owner', 'admin'])`. That means authenticated users can call the endpoint, but only project owners and admins can successfully create invites. There is no evidence of token-based API authentication in the provided code, so this should be documented as session-authenticated unless another auth layer exists outside the snippet.
Request Details **Path parameters** - `projectId` (string, required): Unique project identifier used to scope the invite and permission check.
**Headers** - `Content-Type: application/json` - Auth session cookie or equivalent session header, required by `requireSession()`
**Request body schema** ```json { "email": "[email protected]", "role": "editor", "sendEmail": true } ```
**Validation rules** - `email` must be present, trimmed, lowercased, and pass email validation - `role` must be one of `viewer`, `editor`, or `admin` - `sendEmail` is optional and defaults to `true`
Response Details **Success, 201 Created** ```json { "inviteId": "inv_8f2c1", "projectId": "prj_123", "email": "[email protected]", "role": "editor", "status": "pending", "expiresAt": "2026-05-02T10:30:00.000Z" } ```
**Error responses** - `400 Bad Request`: invalid email, invalid role, or malformed JSON body - `403 Forbidden`: caller is authenticated but lacks admin or owner role - `409 Conflict`: an active invite for the same email already exists in this project
Business Logic Notes - Invite expiration is derived from `now + 7 days`, not supplied by the caller - Duplicate checking happens before insert, but the snippet does not show a unique DB constraint, so concurrent requests may still race unless enforced elsewhere - If `sendEmail` is true, the endpoint queues `mail.enqueueProjectInvite()` after the database write
Edge Cases and Limitations - The code does not show rate limiting, so bulk invite abuse protection is unclear - Error handling around email queue failure is ambiguous. If queuing fails after insert, the invite may exist without an email being sent - There is no visible audit-log write, which may matter for enterprise customers
Open Questions - Is there a database uniqueness constraint on `(projectId, email, status=pending)`? - What happens if `mail.enqueueProjectInvite()` fails after the invite row is created? - Are service tokens allowed to use this endpoint, or only browser sessions?
Ready-to-publish docs block in clean Markdown ### Create a project invite Creates a pending invite for a new project member. Only project owners and admins can call this endpoint. The server validates the email, checks the requested role, prevents duplicate active invites, and returns the new pending invite object.
**POST** `/v1/projects/{projectId}/invites`
**Requires authentication:** Yes **Required role:** `owner` or `admin`
#### Request body - `email` string, required - `role` enum (`viewer`, `editor`, `admin`), required - `sendEmail` boolean, optional, default `true`
#### Success response Returns `201 Created` with the pending invite object, including `inviteId`, `projectId`, `email`, `role`, `status`, and `expiresAt`.
#### Common errors - `400` invalid input - `403` insufficient permissions - `409` duplicate pending invite
API documentation usually breaks in a predictable way. The endpoint ships, the code changes twice, and the docs either lag behind or never appear at all. The result is familiar: engineers read handlers directly, partner teams ask the same questions in Slack, and support becomes the unofficial source of truth.
This Prompt is built for that gap. It takes route definitions, handler code, validation schemas, and example payloads, then turns them into structured docs another developer can actually use. The important part is not just the summary. The Prompt forces the model to separate documented behavior from assumptions, list likely error cases, and surface open questions when the code is unclear.
The structure matters. The Role frames the model as both a technical writer and a backend engineer, which improves precision. The Constraints are doing real work here: they block invented auth rules, guessed parameters, and fake status codes. That is essential for API writing, where a confident wrong sentence is worse than a missing one.
The Output Format also makes this Prompt practical. Instead of producing a vague explanation, it returns endpoint details, request and response documentation, business logic notes, edge cases, and a ready-to-publish Markdown block. That means a developer can go from code to docs draft in one pass, then spend review time fixing the truly ambiguous parts instead of writing from a blank page.
If your team ships internal APIs, partner APIs, or public developer products, this is the kind of Prompt worth saving. It reduces release friction and makes documentation more trustworthy because it starts from the code that actually runs.