Complete API Documentation Suite

API Documentation — Verified Against Every Route

SpeyBooks now ships with a complete .doc.ts documentation layer covering all 165 endpoints across 37 resources. Every example response has been stress-tested against the actual Fastify routes, Zod schemas, and database queries to ensure what the docs say is exactly what the API returns.

This is the documentation that will power the developer portal at launch.

What’s Documented

• Universal Ingestion Engine — full preview arrays (rows[], lines[], mappings[], preview[]) exposed in upload, GET, and map responses. Developers building import wizards get everything they need in a single round-trip.
• Universal Contact Index — DSU graph outcomes (CREATE, MERGE, CONFLICT) with evidence arrays showing why contacts were linked, including hard-key matches and soft-similarity scoring.
• Opening Balance Closure Engine — 5-tier account resolution (exact, code, dictionary, fuzzy, clearing redirect) with confidence scores and clearing mode documentation.
• Outstanding Document Engine — per-row contact resolution showing UCI-lite matching outcomes (match, fuzzy, create) with Levenshtein similarity ratios.
• Migration Wizard — full formatMigration payloads at every state transition, so frontends can render wizard progress without secondary requests.
• Auth & Security — complete user profile objects across login, TOTP verify, and /me endpoints. Token lifecycle, Argon2id hashing parameters, and rotation grace periods all documented.
• Reports — VAT return breakdown array with per-rate net/VAT amounts, liability movement, and all nine HMRC boxes. Dashboard tax set-aside calculations with corporation tax banding.
• Admin — omni-search, GDPR hard-delete cascade, system health monitoring, and settings management.

Consistency Fixes

• Pagination envelope — standardised to meta: { page, perPage, total, pages } across all paginated endpoints. Previously, some documentation examples used a pagination key that didn’t match the paginatedResponse helper.
• Organisation address asymmetry — the GET/PUT shape difference (nested address object in responses, flat addressLine1/city/postalCode fields in requests) is now explicitly documented to prevent 400 validation errors.
• Audit timestamps — createdAt and completedAt now appear in all import and migration response examples.

Developer Experience

• No extra round-trips — upload and map responses return the full preview payload, so there’s no need for a subsequent GET call.
• UI hydration — auth endpoints return complete user context (email, isAdmin, totpEnabled) immediately, eliminating the need for a follow-up /me request after login.
• Transparency endpoints — full severity breakdown (critical, high, medium, low) and lastUpdated timestamp for the public transparency page.