spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# Examples — API Documentation House Style78## Contents9- Complete worked example: one endpoint (bad → house style)10- Error-table examples11- Shared-concepts section pattern12- Changelog entries13- Gotchas1415## Complete worked example: one endpoint1617**❌ Before:**1819```markdown20### Create invoice2122Creates an invoice. Send a POST request with the invoice data.23Returns the invoice object, or an error code if something goes wrong.2425    curl <api-url>/invoices -d foo=bar26```2728**✅ After (house style):**2930```markdown31### Create an invoice3233`POST /v1/invoices` — creates a draft invoice for a customer.3435Requires: `Authorization: Bearer` with an `invoices:write` key.3637**Parameters**3839| Name | Type | Required | Default | Constraints |40|---|---|---|---|---|41| `customer_id` | string | yes | — | existing customer, `cus_` prefix |42| `amount` | integer | yes | — | cents, 50–999999 |43| `currency` | string | no | `usd` | ISO 4217, lowercase |44| `due_date` | string | no | +30 days | ISO 8601 date, future |4546**Request**4748    curl https://api.acme.com/v1/invoices \49      -H "Authorization: Bearer sk_test_51HxTmA..." \50      -d customer_id=cus_9XKzR2 \51      -d amount=1999 \52      -d currency=usd5354**Response — 201**5556    {57      "id": "inv_7GtQpN",58      "customer_id": "cus_9XKzR2",59      "amount": 1999,60      "currency": "usd",61      "status": "draft",62      "due_date": "2026-09-04",63      "created_at": "2026-08-05T14:03:22Z"64    }6566**Errors**6768| Status | Code | When | Fix |69|---|---|---|---|70| 400 | `amount_out_of_range` | amount below 50 or above 999999 | adjust the amount |71| 401 | `invalid_api_key` | missing/revoked key | check the key and its prefix (test vs live) |72| 403 | `missing_scope` | key lacks `invoices:write` | create a key with the scope |73| 404 | `customer_not_found` | unknown `customer_id` | create the customer first |74| 429 | `rate_limited` | over 100 req/min | back off per `Retry-After` |75```7677What changed: full seven-part block; five-column parameter table; runnable78curl with realistic fake data; actual JSON response; errors with when + fix.7980## Error-table examples8182✅ Each row actionable:83`| 409 | idempotency_conflict | same Idempotency-Key with a different body | use a new key or resend the original body |`8485❌ Non-actionable:86`| 409 | conflict | conflict occurred | — |`8788## Shared-concepts section pattern8990Write once, link everywhere:9192```markdown93## Pagination9495List endpoints return at most `limit` items (default 20, max 100) and a96`next_cursor`. Pass it as `cursor` to fetch the next page. Cursors expire97after 24 h.9899    curl "https://api.acme.com/v1/invoices?limit=50&cursor=eyJpZCI6..."100```101102Every list endpoint then says: "Paginated — see [Pagination](#pagination)."103Never re-explain pagination per endpoint (copies drift).104105## Changelog entries106107✅ "2026-06-01 — **Breaking:** `total` renamed to `amount_total` on invoice108objects. Both fields returned until 2026-09-01; update readers before then."109110❌ "June: minor improvements to invoice responses."111112## Gotchas113114- **"foo/bar" sample data** signals the example was never run; use realistic115  prefixed IDs (`cus_`, `inv_`) and plausible amounts.116- **Documenting the spec, not the behavior:** if the server returns fields117  the spec omits, the docs are wrong until reconciled — test against the118  real API.119- **Error tables copied between endpoints** rot instantly; generate them per120  endpoint or verify each row.121- **Auth examples with live-mode keys** get copy-pasted into scripts; always122  show `sk_test_` keys.123- **Undocumented defaults** force callers to reverse-engineer; every optional124  parameter states its default, even when it's "empty".125