API Documentation Writer

---
name: api-documentation-writer
description: Use when documenting an API endpoint, library function, or module for external or cross-team consumers. Triggers on "document this API", "API docs", "function docs", "endpoint reference".
---

# API Documentation Writer

Auto-generated docs that just restate the type signature are useless. The reader already has the type signature. They need the things the type can't tell them: when to use this, when NOT to, what the realistic examples look like, and what surprises lurk in the edge cases.

## Required inputs

1. **What's being documented** — function signature, endpoint, module
2. **What it actually does** — in plain language, not just types
3. **The inputs** — types, required vs optional, validation rules
4. **The outputs** — success shape, error shape, status codes
5. **A realistic call site** — where would someone actually use this?
6. **Known gotchas** — auth, rate limits, idempotency, side effects

If the user only has the type signature, push back: "What's a real use case for this? What's something a consumer would get wrong if they only saw the types?"

## Structure (for an endpoint or function)

```
# [Method] [Path] OR FunctionName(...)

## What it does
1-2 sentences. The user-visible effect, not the implementation.
GOOD: "Creates a checkout session and returns a redirect URL for the hosted payment page."
BAD: "Calls the createCheckout method on the CheckoutService."

## When to use
- Bullet list. The realistic scenarios.

## When NOT to use
- Adjacent endpoints/functions that are easy to confuse
- Cases where another API is the right tool

## Authentication / permissions
What credentials, scopes, or roles are required. Be specific.

## Request / parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | string (UUID) | yes | The customer placing the order |
| items | Item[] | yes | Min 1, max 100 |
| coupon | string \| null | no | Coupon code; null applies no discount |

For each non-trivial parameter, add a 1-line note: format requirements, valid values, default behavior.

## Response (success)

\`\`\`json
{
  "id": "co_01HXYZ...",
  "url": "https://...",
  "expires_at": "2026-04-29T10:00:00Z"
}
\`\`\`

Notes on fields that aren't obvious — formats, time zones, mutability.

## Errors

| Status | Code | When | What to do |
|--------|------|------|------------|
| 400 | invalid_email | email failed regex | Fix client validation |
| 402 | card_declined | issuer declined | Show user message, offer retry |
| 409 | idempotency_replay | same key, different body | Bug — fix client |

For each error: WHEN it happens (a precondition, not just the message) and WHAT the consumer should do.

## Examples

### Basic
\`\`\`<lang>
[A realistic minimal call — 5-10 lines]
\`\`\`

### With optional features
\`\`\`<lang>
[A second example showing common variants]
\`\`\`

## Edge cases / gotchas

- Idempotency: \`Idempotency-Key\` header recommended; we de-dupe for 24h.
- Concurrency: simultaneous calls with same idempotency key — second returns the first's result.
- Rate limit: 100/min/account.
- Time zones: \`expires_at\` is always UTC.
- The thing that surprises every consumer.

## Related
- Adjacent endpoints/functions
- Migration notes if this replaces something else
```

## Anti-patterns

- "@param userId: the user ID" — repeats the type, says nothing
- Examples that won't compile / can't run as written
- Listing every error code without saying what triggers each
- "See the source" — a doc that punts to the code is not a doc
- Examples using `foo` and `bar` instead of realistic data — readers learn from real shapes

## Tone

- Imperative for instructions, present tense for behavior.
- Plain language. "Returns the user's active subscription, or null if there isn't one." Not "Yields the entity corresponding to..."
- Honest about what's deprecated, beta, or unstable.

## Output

Markdown. Examples in fenced code blocks with `<lang>` tags. Tables for parameters and errors. End with a "Last updated: [date]" line so consumers can tell if the doc is stale.