api-reference-authoring

name	api-reference-authoring
description	Generate or update API and SDK reference docs and examples from code, schemas, OpenAPI, proto files, or existing docs. Prefers accurate reference over marketing language.

API Reference Authoring

Produce or update API and SDK reference content from source. Accurate, complete, and grounded in the actual surface.

Use when

• generating or updating API or SDK reference docs
• enumerating endpoints, functions, parameters, returns, and errors
• adding examples to existing reference docs
• documenting changes to a public surface

Do not use when

• the user wants conceptual guides or tutorials
• the user wants release notes
• the user wants an audit of existing docs

Execution model

Workflow phases:

overview -> enumerate surfaces -> parameters -> returns and errors -> examples -> edge cases -> versioning notes

Enumerate the surface. Walk the source: code, schemas, OpenAPI, proto, or existing docs. List every endpoint, function, type, parameter, return shape, and error code that the source defines.

Parameter discipline. For each parameter: name, type, required vs optional, default if any, valid range or enum, constraints, examples. Do not omit required or default; readers need both.

Errors as first-class content. List error codes or exception types with conditions that produce them. A reference without errors is incomplete.

Examples grounded in the surface. Each example must match the actual signature and types. If the source does not show a working call, mark the example illustrative rather than fabricating runtime behavior.

Hard rules

• Prefer accurate reference over marketing language.
• Include parameter required, default, type, and constraints; never silently drop these.
• Document error codes or exception types and the conditions producing them.
• Include request and response examples only when supported by the source; mark unsupported examples illustrative.
• Include Mermaid only when flow or lifecycle clarifies usage; never as decoration.
• Do not invent endpoints, functions, types, parameters, or response fields.
• Note versioning, deprecations, and compatibility implications where present in source.
• Works standalone; does not require any companion prompt.

Artifact format

Use only sections that matter.

overview: what the API or SDK does, its scope, and base URL/import path where applicable.

endpoints-or-functions: enumerated list; signature, purpose, source tie.

parameters: name | type | required | default | constraints | description; per endpoint or function.

return-values-or-responses: shape, types, semantics, success codes for HTTP.

errors: code or type | condition that produces it | suggested handling.

examples: request and response examples; cite source where applicable; mark illustrative if not directly supported.

edge-cases: pagination, retries, idempotency, rate limits, timeouts, partial results, ordering guarantees.

versioning-or-compatibility-notes: version surface, deprecations, breaking-change history if known from source.

Response format

End each response with: scope, confidence (high|medium|low), status, key assumptions or surface areas not verified, next-step (only if useful).