API Endpoint Reference
Turns route code, schemas or captured requests into endpoint reference docs with parameter tables, full examples and error fixes.
When to use itUse it when an API exists in code but its docs are missing or out of date. Paste the validation schemas and error handling, not only the handler: the model documents only the parameters and status codes it can see, and cannot call the API to check them.
- Type
- Playbook
- Inputs it asks for
- 06
- Sections it returns
- 04
- Quality checks
- 07
On this page5 sections
Asks for
What you hand it before it runs. Required ones are marked.
- 01Source materialLong textRequired
Route handlers, an OpenAPI or JSON Schema spec, validation schemas, type definitions, captured requests and responses, or existing notes. Include the error-handling code so status codes can be documented.
- 02Tested againstText
API version and the date the examples were last called, e.g. v1, called on 2026-10-10. Left blank, the reference flags it.
- 03Base URLText
e.g. https://api.example.com/v1. Left blank, examples use BASE_URL as a placeholder.
- 04AuthenticationText
How requests authenticate, e.g. a bearer token in the Authorization header. Left blank, it is documented from the source or flagged.
- 05Example formatSelect
Language for the request examples. Defaults to curl.
- 06Endpoints to coverText
Limit the reference to these, e.g. POST /orders, GET /orders/{id}. Left blank, every endpoint in the source is documented.
Method
The instruction the model follows, word for word as it ships in the SKILL.md.
You write API reference documentation from the Source material. The Technical Documentation Writer rules apply throughout (source only, [VERIFY] flags and the To verify list, show then explain, action plus expected result, ALL_CAPS placeholders, labelled shell syntax, precise verbs). This method adds only what is specific to endpoint references.
The reference succeeds when a developer can make a correct first call to each endpoint, and act on each documented error, without reading the code.
Sourcing for APIs: take each parameter's name, location, type, required status, default and limits from the schema, validation or handler code, never from naming conventions or from what similar APIs usually do. A field the handler reads but no schema declares is still documented, with its type flagged. Document only the status codes the code returns or the spec declares. If the framework is likely to add others (a validation error, for example) and the source does not show them, flag them instead of listing them.
Structure:
- H1: the API or resource name. Directly under it, one line: "Tested against: " followed by the Tested against value. If Tested against is blank, write "Tested against:
[VERIFY: version and date last run]". - Overview: two or three sentences on what the endpoints cover, then the base URL (from Base URL, the source, or BASE_URL) and the request and response content type.
- Authentication: how to authenticate, from the Authentication field or the source, with one header example using a placeholder such as YOUR_API_TOKEN. State it here once rather than per endpoint. If the source shows no authentication, write "No authentication shown in the supplied material." and flag it.
- Endpoints: one H3 per endpoint, titled with the method and path ("### POST /orders"), in the order the source defines them, limited to Endpoints to cover when it is filled in. Under each, in this order: 1. One sentence on what the call does. 2. Parameters: a table with the columns Name, In (path, query, header or body), Type, Required, Description. Nested body fields use dot notation (items.sku). Write "None." when there are none. 3. Request example: a complete call in the Example format (curl when blank), with the auth header, a realistic body and placeholders for IDs and secrets. 4. Response example: the status code and the full body. Use a captured response from the source when there is one; otherwise build it from the response type or schema and label it "Illustrative, built from the response schema." Follow it with a table of response fields: Field, Type, Description. 5. Errors: a table with the columns Status, Meaning, Fix, covering the status codes established above. The Fix says what the caller changes, not what the server does.
- To verify: the numbered list of every
[VERIFY]flag, each with its endpoint and what would settle it.
The shape of one parameter row (shape only; the content must come from the source):
Example
Keep prose to the one-sentence descriptions and short table cells. If an endpoint has no request shape in the source (no schema, types or example), document its method and path, write "Request shape not in the supplied material." and flag it rather than guessing a body. If the source contains no endpoints at all, ask for the route code or spec instead of writing.
Returns
Every reply comes back in this shape, in this order.
- 01Overview
- 02Authentication
- 03Endpoints
- 04To verify
Quality checks
Read the reply against these before you use it. Tick them off as you go; nothing is saved.
0 of 7 checked
SKILL.md
The whole playbook as one skill file, for Claude, Codex or any tool that reads SKILL.md.
---name: "api-endpoint-reference"description: "Turns route code, schemas or captured requests into endpoint reference docs with parameter tables, full examples and error fixes."--- # API Endpoint Reference You write API reference documentation from the Source material. The Technical Documentation Writer rules apply throughout (source only, [VERIFY] flags and the To verify list, show then explain, action plus expected result, ALL_CAPS placeholders, labelled shell syntax, precise verbs). This method adds only what is specific to endpoint references. The reference succeeds when a developer can make a correct first call to each endpoint, and act on each documented error, without reading the code. Sourcing for APIs: take each parameter's name, location, type, required status, default and limits from the schema, validation or handler code, never from naming conventions or from what similar APIs usually do. A field the handler reads but no schema declares is still documented, with its type flagged. Document only the status codes the code returns or the spec declares. If the framework is likely to add others (a validation error, for example) and the source does not show them, flag them instead of listing them. Structure:- H1: the API or resource name. Directly under it, one line: "Tested against: " followed by the Tested against value. If Tested against is blank, write "Tested against: [VERIFY: version and date last run]".- Overview: two or three sentences on what the endpoints cover, then the base URL (from Base URL, the source, or BASE_URL) and the request and response content type.- Authentication: how to authenticate, from the Authentication field or the source, with one header example using a placeholder such as YOUR_API_TOKEN. State it here once rather than per endpoint. If the source shows no authentication, write "No authentication shown in the supplied material." and flag it.- Endpoints: one H3 per endpoint, titled with the method and path ("### POST /orders"), in the order the source defines them, limited to Endpoints to cover when it is filled in. Under each, in this order:Used together with
- 01Technical Documentation WriterWrites setup guides, API references, READMEs and runbooks from your source material, and flags anything it cannot confirm.Operator
- 02READMEWrites a README from your manifest, code and tests: what it does, a quick start of five steps or fewer, real usage examples and licence.Playbook
- 03Setup GuideTurns code, config files and install logs into a setup guide where every step shows the command and the result to expect.Playbook
Free to use and adapt under CC BY 4.0. Credit MyPromptVerse.
Built in MyPromptVerse. Follow the build →