Api Documentation

API Documentation

Use this skill when the main job is publishing or refreshing developer-facing API docs that help integrators reach first success, understand reference truth, and stay unblocked as the API evolves.

api-documentation is the documentation-cluster anchor for:

• endpoint / schema reference docs
• quickstarts and first-success flows
• task-oriented integration guides
• SDK guides
• webhook delivery / verification docs
• developer-portal navigation and grouped reference surfaces
• migration updates attached to the docs surface

Read these support docs before choosing the mode or output packet:

• references/documentation-modes-and-boundaries.md
• references/output-packets-and-navigation.md
• references/example-and-reference-checklist.md
• references/publishing-and-drift-control.md

When to use this skill

• A team needs API reference, quickstarts, or portal pages that external developers, partners, or internal integrators can actually use.
• An OpenAPI or schema artifact already exists, but the docs need structure, examples, auth/setup guidance, error handling, or clearer navigation.
• Existing API docs drifted after auth, versioning, retry, pagination, webhook, or SDK changes.
• A public, partner, or internal API launch needs developer-facing guides, migration notes, or trustworthy examples.
• A large API surface needs grouping, selective publishing, or cleaner portal structure instead of one giant reference dump.

When not to use this skill

• The main job is designing resources, endpoint shape, schema rules, or versioning strategy → use api-design.
• The main job is writing internal specs, ADRs, runbooks, rollout docs, or system migration procedures → use technical-writing.
• The main job is end-user/product UI onboarding, screenshots, tutorials, or help-center docs → use user-guide-writing.
• The main job is implementing auth/session/provider behavior rather than documenting how API consumers authenticate → use authentication-setup.
• The main job is release-note, semver, or changelog hygiene → use changelog-maintenance.
• There is no credible source of truth for the API behavior yet → route missing contract questions back to api-design instead of inventing docs from vibes.

Instructions

Step 1: Classify the API-doc job

Normalize the request before drafting.

api_documentation_mode:
  primary_mode: reference | quickstart | task-guide | sdk-guide | webhook-guide | migration-update
  api_style: rest | graphql | webhook | sdk | mixed | unknown
  audience: external-developers | internal-integrators | partners | mixed | unknown
  source_of_truth: openapi | graphql-schema | code-annotations | tests | mixed | unknown
  docs_surface: developer-portal | docs-site | repo-markdown | sdk-site | internal-catalog | unknown
  navigation_scope: single-operation | grouped-resource | large-api-surface | portal-section | unknown
  maintenance_state: new-docs | refresh | drift-fix | launch-critical

Choose one primary mode per run:

• reference → endpoint/schema truth with parameters, fields, errors, limits, and examples
• quickstart → fastest path to first successful API call or webhook receipt
• task-guide → one workflow or integration outcome
• sdk-guide → language/client-library guidance plus examples and caveats
• webhook-guide → delivery, verification, retry, and local-debug guidance
• migration-update → changed behavior and transition path on the docs surface

If the surface is large, also decide whether the task is about grouping/navigation as much as prose. Do not hide large-surface information architecture inside a generic “write docs” request.

Step 2: Confirm boundary skills and the real developer job

Answer these four questions before writing: 1. Who is integrating with this API, and what exact job should they complete after reading? 2. What artifact is the real contract source of truth today? 3. Which docs surface are you updating: portal, repo docs, SDK site, internal catalog, or mixed? 4. Which neighboring skills must stay out of scope?

Quick route-out table:

Step 3: Gather the smallest truthful evidence set

Do not write API docs from an outdated spec alone. Pull the minimum credible evidence first:

• current OpenAPI / GraphQL schema / endpoint list / SDK surface
• auth requirements: keys, headers, scopes, signing, sandbox vs production, callback/webhook verification
• example requests and responses that match current behavior
• common errors, retries, limits, pagination/cursor behavior, and idempotency expectations
• versioning, deprecation, and migration notes
• tests, fixtures, or verified requests that keep examples honest
• publishing constraints: portal nav, selective publishing needs, docs-site structure, or internal-catalog grouping

If details are incomplete, label assumptions clearly and produce a docs-gap list instead of faking certainty.

Step 4: Choose the smallest useful packet

Match the output to the developer job. Do not dump quickstart, reference, SDK docs, and migration notes into one giant page by default.

Common packet choices:

• one quickstart page
• one grouped reference section
• one task/integration guide
• one SDK guide
• one webhook guide
• one migration-update note
• one docs-gap / drift checklist for unresolved truth-source issues
• one navigation/grouping proposal for a large API surface

Use references/output-packets-and-navigation.md for mode skeletons and portal/grouping guidance.

Step 5: Apply API-doc rules instead of generic writing advice

Use these rules aggressively:

• Lead with the developer task and integration surface, not marketing copy.
• State auth and environment assumptions early.
• Keep examples truthful: prefer tests, verified requests, or real fixture shapes.
• Document operational realities: errors, retries, limits, pagination, webhook replay, eventual consistency, idempotency.
• Separate reference truth from workflow guidance.
• Expose navigation decisions on large APIs: grouping, selective publishing, and related-guide links matter.
• Link outward deliberately: quickstarts point to deeper reference; reference points to task guides; migration updates point to changelog/release notes rather than replacing them.

Step 6: Protect against drift on purpose

Before finalizing, record:

• contract source of truth
• example source of truth
• publishing surface
• review trigger
• drift hotspots: auth, limits, retries, versioning, webhook fields, SDK examples, migration notes
• companion docs that must stay aligned: quickstarts, SDK pages, changelog entries, Postman collections, portal navigation

Use references/publishing-and-drift-control.md as the anti-drift checklist.

Step 7: Verify output quality

Before shipping, check: 1. Could a new integrator reach first success with this doc set? 2. Are auth and environment assumptions visible before the first call? 3. Do examples match real behavior? 4. Are errors, limits, retries, pagination, or verification notes present where needed? 5. Is the output packet small enough for the request? 6. Are route-outs to api-design, technical-writing, user-guide-writing, authentication-setup, and changelog-maintenance still explicit?

Examples

Example 1: Partner API quickstart

Input: “Write the quickstart for our Orders API so partners can create an API key, send the first POST /orders, and verify the returned order ID.”

Good output shape: chooses quickstart, shows prerequisites and auth early, gives one first-success request plus a success check, and links to the deeper reference surface.

Example 2: Large reference cleanup

Input: “Our developer portal publishes one huge OpenAPI collection; help us regroup endpoints, expose only partner-safe sections, and add navigation that developers can scan.”

Good output shape: treats this as reference plus navigation/grouping work, proposes grouped sections or selective publishing, preserves truthful reference links, and does not pretend auto-generation alone solves the structure problem.

Example 3: Webhook change notice

Input: “Update our webhook docs because invoice.paid now retries for 24 hours, includes attempt_count, and requires HMAC verification on every delivery.”

Good output shape: chooses webhook-guide or migration-update, documents retry and verification behavior, updates affected examples, and keeps implementation details and release-note hygiene out of scope.

Example 4: Route-out to API design

Input: “We haven’t decided whether this should be REST or GraphQL, and we need a resource model and pagination plan.”

Good output shape: routes the task to api-design, explains that contract/interface work must happen before docs publication, and may note what docs surfaces will be needed later.

Best practices

1. Treat API docs as developer workflow artifacts, not as schema rendering alone. 2. Keep contract design separate from developer-facing publication. 3. Prefer small, truthful packets over one giant portal page. 4. Make auth, examples, limits, retries, pagination, and webhook behavior explicit early. 5. Document navigation/grouping decisions for large surfaces instead of burying them in prose. 6. Tie docs maintenance to real truth sources so refreshes do not drift. 7. Route adjacent writing, auth implementation, and release hygiene tasks to the right neighboring skill.

References

• OpenAPI Initiative
• Stripe API Reference
• GitHub REST API docs
• ReadMe Guides
• Redocly docs
• Postman API documentation

API Documentation Modes and Boundaries

Use api-documentation for developer-facing API docs that help integrators succeed after the contract already exists.

Canonical modes

1. Reference docs

Use when developers need endpoint, schema, field, or error truth.

Typical signals:

• endpoint reference
• parameter/field tables
• response schema
• error/status code docs
• pagination, limits, retries

2. Quickstart

Use when the job is first success, not exhaustive reference.

Typical signals:

• get an API key
• make the first request
• verify a response
• choose sandbox vs production
• next steps into deeper docs

3. Integration guide

Use when one task or workflow needs a guided path.

Typical signals:

• "how to sync orders"
• "how to upload files"
• "how to paginate through results"
• "how to recover from webhook retries"

4. SDK guide

Use when a client library needs install/config/usage guidance.

Typical signals:

• package install
• client configuration
• first working example
• error handling conventions
• version compatibility notes

5. Webhook guide

Use when delivery, verification, retries, and local-debug flows matter.

Typical signals:

• event registration
• signature verification
• idempotency
• replay/retry behavior
• local listener setup

6. Migration update

Use when a changed API needs a docs-facing transition path.

Typical signals:

• deprecated field or endpoint
• new version path
• changed auth or pagination semantics
• compatibility deadline
• old-vs-new example pairs

Boundary table

Common failure modes

• Dumping a raw OpenAPI schema into docs and calling it done
• Mixing quickstart, full reference, SDK setup, and release notes into one giant page
• Confusing contract design questions with documentation tasks
• Hiding auth assumptions and environment setup until halfway through the guide
• Publishing examples that do not match current API behavior

Example and Reference Checklist

Use this checklist before shipping API docs.

Minimum developer-success set

• One first-success example request
• One realistic success response
• Auth prerequisites and header/signing details
• One common error and recovery note
• Environment/base-URL note if sandbox and production differ
• Link to the deeper reference surface for full parameters/fields

When the API is more complex

Add any that apply:

• pagination example
• retry/backoff note
• idempotency key example
• webhook signature verification example
• version/deprecation example
• SDK example paired with raw HTTP
• rate-limit note and what to do when exceeded

Good example rules

• Prefer tested or otherwise verified examples over invented placeholders
• Keep placeholders obvious when secrets or IDs are redacted
• Match field names and error shapes to the real contract
• Include just enough context to run or reason about the example
• Explain why the example matters, not just what it contains

Reference-surface rules

• Put auth before endpoints when every call depends on it
• Keep common conventions together: base URL, headers, versioning, limits, retries
• Group operations by developer job or resource, not random internal service layout
• Keep error docs close to the relevant operation or in a clearly linked common section
• Show what success looks like after the call, not only the request syntax

Output Packets and Navigation

Use this reference when api-documentation has already been selected and you need the smallest useful artifact shape.

Mode skeletons

1. Reference packet

Use when developers need endpoint/schema truth.

# <API / Service> Reference

## Base URL / environments
## Authentication
## Common headers and conventions
## Grouped operations / resources
## Request parameters
## Response schema / example payloads
## Errors and status codes
## Pagination / rate limits / retries
## Related guides

2. Quickstart packet

Use for first-success onboarding.

# Quickstart: <First successful API task>

## What you will do
## Prerequisites
## Step 1: Get credentials / access
## Step 2: Make the first request
## Step 3: Verify success
## Common mistakes
## Next guides

3. Task / integration guide packet

Use for one workflow beyond raw reference.

# How to <Integration outcome>

## When to use this flow
## Prerequisites
## Step 1
## Step 2
## Step 3
## Verify success
## Failure modes / retries
## Related reference sections

4. SDK guide packet

Use when a client library needs install/config/usage guidance.

# <SDK name> guide

## Install / import
## Configure credentials and environment
## First working example
## Common operations
## Error handling / retries
## Version compatibility notes
## Links to raw API reference

5. Webhook guide packet

Use for event-driven integrations.

# Webhook integration guide

## Event delivery model
## Registering an endpoint
## Signature verification
## Retry / idempotency rules
## Local development and testing
## Event payload examples
## Failure troubleshooting

6. Migration update packet

Use when behavior changed and the docs need a developer-facing transition path.

# <API / SDK> migration update

## What changed
## Who is affected
## Deprecated behavior
## New behavior / examples
## Migration steps
## Timeline and compatibility notes
## Related changelog / release notes

7. Docs-gap packet

Use when the documentation request exposed truth-source gaps.

# API documentation gaps

## Confirmed truths
## Missing contract questions
## Example gaps
## Drift hotspots
## Required route-outs

Navigation and grouping guidance

Use this layer when the request is about a large API surface, not just a single page.

Good triggers

• "The portal is one huge generated reference"
• "We need partner-safe sections only"
• "The left nav is too noisy"
• "Internal-only endpoints are mixed with public ones"
• "Webhook, SDK, and reference docs are blended together"

Navigation rules

• Group by developer job or resource family, not by random internal service layout.
• Separate quickstarts, reference, SDK docs, webhook docs, and migration/changelog updates into distinct surfaces.
• If selective publishing matters, list what should be public, partner-only, internal, or hidden until stable.
• Keep deep links stable for high-traffic sections: auth, errors, pagination, limits, webhook verification, migration notes.
• When a large spec is published, document the grouping logic explicitly instead of assuming autogenerated tags are good enough.

Source-of-truth patterns

• spec-first → OpenAPI/schema drives reference; guides stay editorial
• code-first → code annotations render reference; examples and guides still need owner review
• test-backed → verified requests/fixtures keep examples honest
• hybrid → spec + tests + editorial guides + changelog/update notes

Record the pattern instead of pretending the whole docs set is one artifact.

Publishing and Drift Control

API docs decay when rendering and writing are treated as one-time generation tasks.

Decide the maintenance chain

Record four things explicitly: 1. contract source of truth (OpenAPI/schema/code annotations) 2. example source of truth (tests, fixtures, verified requests, SDK snippets) 3. publishing surface (portal, docs site, repo Markdown, SDK site) 4. review trigger (release, endpoint change, auth change, migration, incident)

Drift hotspots

Check these first on every refresh:

• auth requirements or scopes
• sandbox vs production details
• base URL / version path changes
• error payloads
• pagination/cursor behavior
• rate limits and retries
• webhook event fields and signatures
• SDK install/config examples
• deprecated endpoints/fields and migration notes

Lightweight anti-drift tactics

• link docs work to release reviews when API behavior changes
• derive examples from tests or verified requests when possible
• keep migration updates near the affected docs, not only in release notes
• use docs-gap notes when the contract is ambiguous instead of faking certainty
• separate reference rendering from editorial review so portal output still gets human quality checks

Route-out reminder

When the docs task exposes an unresolved contract question, route the open question to api-design and keep the documentation work honest.