authoring-api-reference

Derive every endpoint, parameter, field type, and error directly from the OpenAPI contract, then add a getting-started quickstart, an authentication walkthrough, and worked request/response examples per operation. Never invent endpoints or fields the contract does not declare.

Each endpoint needs the method and path, a purpose line, typed parameters marked required or optional, a worked request example, a worked success response, at least one failure response, and the error status codes it returns. A block showing only the 200 response is incomplete.

If the project auto-generates the endpoint catalog with tools like Redocly, Swagger UI, or Mintlify, do not re-type it since duplicates drift immediately. Focus human effort on the getting-started narrative, example quality, and a drift check over the generated output.

Document one consistent error shape, preferably RFC 9457 Problem Details, with a machine-readable code distinct from the HTTP status plus a status-code table. For rate limits, state the limit, the 429 signal, Retry-After, exponential backoff with jitter, and idempotency keys for safe retries.

Scope the change to affected endpoints, re-sync only those blocks against the changed contract, and re-check every worked example the change touches. Mark removed endpoints deprecated with a sunset date and migration path rather than silently deleting them, then bump the doc version and amend log.

Do not use it to write the engineering wire contract itself, which is the upstream api-spec's job, or end-user product guides and SDK tutorials, which target a different audience. It also does not cover rendered docs-site concerns like search, interactive try-it consoles, or accessibility.