API Reference Integrity — All 37 Resources Re-Verified Against the Live Implementation
Why This Matters
API documentation that drifts from the running system is worse than no documentation. A developer integrates against the reference and only discovers the gap in production, under customer data. This release closes a structured campaign to re-derive every documented resource directly from the live route handlers, so the reference describes what the API does, not what it was once intended to do.
The verification was deliberately adversarial. Each resource was reviewed by two independent parties, with the second re-deriving every claim from the implementation rather than checking the first reviewer’s reasoning. Two people sharing the same assumption is exactly the failure that ordinary documentation review misses. The standard applied was simple: no sentence in the documentation states something the reviewer could not witness at a specific line in the deployed code.
This discipline produced 37 verified resources. It also produced a body of findings that went beyond documentation correction.
Reference Verification
All 37 documented resources re-derived from the implementation
Every documented resource’s fields, limits, error codes, behaviours, and examples were re-derived from the live route handlers. Where the documentation and the implementation disagreed, the documentation was corrected to match the running system. Where the implementation was incorrect, the finding was raised as a code-level item.
Resources span every surface: financial (transactions, invoices, quotes, dividends, director loans, VAT, opening balances), identity and access (auth, registration, email verification, password reset, API keys), administrative (organisations, contacts, bank imports, invoice imports, bill imports, contact imports), developer infrastructure (webhooks, API request log, health), and internal operations (admin, transparency, public trust).
Signature verification recipe corrected
The outbound webhook signature verification recipe documented in the reference no longer matched what the delivery system produces. The prior documentation described a payload-only signing approach; the implementation uses a timestamped scheme with replay protection. The reference now documents the exact string that is signed, the header format, and the step-by-step verification, so an integrator following the documentation verifies correctly rather than failing every check.
This sits on a capability documented ahead of general availability; see Known Issues.
Financial correctness findings
Two findings surfaced where documented aggregate figures do not match what the underlying queries return.
The retained profits figure used to gate dividend declarations does not filter by transaction status. Draft journal entries count toward the distributable figure that authorises real distributions. A board minutes resolution can be approved against an inflated retained earnings number. The finding is raised; the fix is under active work.
The contact financial summary presents figures as amounts billed and amounts owed. The underlying query counts invoices of all statuses, including drafts and cancelled records. The finding is raised; the ruling on which statuses a financial summary should include is part of the active work.
Security findings raised
Several code-level security findings were surfaced during the verification pass and are under active remediation.
The forgot-password reset flow does not invalidate outstanding session tokens. A password change does invalidate them; the reset does not. An attacker holding a token at the point of reset retains access until that token expires. The fix is one targeted addition to the reset path and has been prioritised.
The admin impersonation handler does not enforce its own documented restriction on impersonating administrative accounts. The documented behaviour and the implemented behaviour disagree. The fix is under active work.
These are raised as findings rather than included in this release. Remediation changelog entries will follow when the fixes are deployed.
Schema and vocabulary corrections
Where documented error codes, field names, or enumerated values did not match the values the API actually returns, the documentation was corrected. One finding across import surfaces was that the same rejection condition returns two different error codes depending on which surface is called. The finding is tracked for resolution.
Documented example values were verified against the types and constants in the running code. Several examples carried version strings, status values, and outcome labels that were not values the implementation could produce. All examples were corrected to satisfiable values.
Redaction pass
Documentation that named internal implementation details was revised to document behaviour rather than mechanism. This applies across all surfaces: engine names, internal constants, query structures, and algorithm parameters are not part of the integration contract and have been removed from the public reference. The documented outputs and their semantics remain, fully specified.
Operational Impact
- The API reference now describes verified behaviour for all 37 documented resources, re-derived from the implementation under two-party review.
- Documented fields, limits, error codes, and examples match the running system as at this release.
- Corrections were made at the documentation source, so the reference and the implementation are reconciled rather than annotated.
- Code-level findings surfaced during verification are tracked and under active remediation. Changelog entries will follow each fix.
Files Changed
Backend: None. No runtime behaviour changed in this release.
Documentation: API reference content for all 37 documented resources, re-derived against the live route handlers under two-party review.
Known Issues
Outbound webhook delivery is documented ahead of general availability. The webhook reference now documents the delivery and signature behaviour of the outbound delivery subsystem accurately against the deployed implementation. That subsystem is built and in preparation; registering an endpoint does not yet produce deliveries. A future release will enable outbound delivery, at which point the documented behaviour becomes live.
With all 37 documented resources verified against the implementation, the reference is now held to the same standard as the code it describes: nothing asserted that was not witnessed.