API documentation prompts: bind prose to a versioned contract

Last updated: 2 Oct 202611 min read

tutorial

An API documentation prompt should receive a bounded evidence packet: the relevant operation contract, implementation behavior, integration tests, and version policy. Identify which artifact defines the public contract when code and schema disagree. The model may draft an explanation, but it must not invent a parameter, status code, response field, or permission from surrounding conventions. State the exact endpoint version and change under review. Ask for a discrepancy ledger before prose if a test and specification differ. Separate public behavior from internal class names; readers need the contract they can call, not an unreviewed dump of source code.

Operational case

A fictional Shipment Status API adds the status held to version two of its shipment response. The endpoint is GET /v2/shipments/{shipmentId}. The approved operation contract allows queued, in_transit, held, and delivered. One old guide lists only three values, while an integration test has a held fixture. The prompt first records that drift and asks the API owner to confirm that held is released in v2. It does not infer that a new hold_reason field exists just because the implementation stores one internally. The public page will be drafted only against the confirmed contract and test fixture.

Scope: GET /v2/shipments/{shipmentId}; version 2.
Packet: approved operation contract, handler behavior, integration tests.
Change: held joins queued, in_transit, delivered.
Conflict: old guide lacks held -> record drift and confirm release.
Unknown: internal hold_reason is not automatically public.

Performance and operating cost

Reading E endpoint artifacts and T relevant tests is O(E+T) inspection work. Restricting the prompt to the changed operation reduces token cost and prevents an unrelated endpoint from contaminating the example. A discrepancy ledger takes extra review but is cheaper than publishing an invented field across several pages. A generated page must be checked against the authoritative contract after editing; a good opening paragraph does not validate every request and response detail.

Common Mistakes

Do not document an internal field as public without contract evidence.
Do not copy an older guide as the only truth when its enum is stale.
Do not mix behavior from different API versions.

Connected lessons

prompt engineering

api documentation