v5.62.0 11 June 2026 Improvement

SpeyDocs Production Gold: API Reference Verified Across Eight Core Resources

Why This Matters

API reference documentation is a contract. When a documented response shape, field meaning, or status value drifts from what the API actually returns, integrations break in ways that are slow and painful to trace back to the docs. SpeyBooks holds its reference to the same standard as its financial core: every documented claim verified against the live implementation, not written from memory. This release brings the reference for eight core resources to that standard in a single coordinated pass, and the audit was rigorous enough to surface improvements beyond the docs themselves, now tracked on the kernel backlog and the transparency page. That is the standard working as designed: documentation that finds things, not just describes things.

Reference Verified Across Eight Core Resources

The API reference for billing, webhooks, transactions, accounts, invoices, quotes, reports, and opening balances was rebuilt against the live API and database, claim by claim. Together these cover the entire money path, from subscription through double-entry ledger to financial reports and opening-position imports.

  • Every claim anchored to a named kernel invariant Behavioural statements in the reference now cite the specific registered invariant that makes them true. When a page says posted transactions are immutable or the books must balance, that sentence carries a reference to the mechanism enforcing it, not an author’s assurance.

  • Response shapes documented as returned Every documented field now matches the actual response, including where a resource nests its persistent record under a sub-object, returns a flatter preview shape elsewhere, or includes computed lines such as the balance sheet’s Retained Earnings row. No more guessing which fields come back from which call.

  • Field semantics corrected Field meanings, allowed values, and nullability were checked against the implementation. Where a documented value set was incomplete or a label was wrong, it was corrected to match the API’s actual behaviour, including the full financial period status vocabulary.

  • Lifecycle and status values made accurate Resource lifecycle states, such as the stages an opening-balance import moves through, are now documented as the API actually transitions them rather than an idealised subset.

  • Money formats stated precisely per resource Where a resource returns monetary values as formatted strings rather than integer minor units, the reference now says so explicitly, so a developer knows the exact shape to parse before writing a line of code.

Worked Examples That Reconcile

  • Examples balance and conserve Every worked example was rebuilt to be internally consistent: trial balances that actually balance, balance sheets that satisfy the accounting equation, debit and credit totals that match the lines shown, and row counts that reconcile. An example a developer can trust is an example they can copy.

Aged Reports

  • Bucket boundaries corrected The documented ageing buckets for the aged debtor and aged creditor reports were corrected to match the boundaries the API uses: current, 1-30, 31-60, 61-90, and 90+ days.

Operational Impact

  • Eight core API resources verified against the live implementation in one pass, under a single documentation standard applied uniformly.
  • Response shapes, field semantics, lifecycle states, and money formats documented exactly as the API returns them.
  • Worked examples are internally consistent: figures balance, counts reconcile, no truncated or unsatisfiable sets.
  • Four endpoint descriptions corrected in the API itself to match actual behaviour; no behavioural change.

Proof anchor: documentation and specification parity verified at every deploy by the six-gate docs pipeline (201 of 201 endpoints covered, pages match the generated specification, live-site verification). Invariant references resolve to the axiom registry, itself machine-verified on every API deploy.

Files Changed

Backend: API endpoint description metadata only (aged-report bucket labels and three rendered resource descriptions). No API behaviour changed in this release.

Frontend / Docs site:

  • API reference at docs.speybooks.com for billing, webhooks, transactions, accounts, invoices, quotes, reports, and opening balances.
    • Response shapes, field documentation, and status values reconciled to the live API
    • Worked examples rebuilt to balance and reconcile
    • Aged-report bucket boundaries corrected

Documentation held to the same standard as the financial core, with the remaining resources to follow on the same pass.