API Reference

This chapter orients you to Fyndow's API surface. A fully generated, browsable endpoint reference (request/response schemas, examples, "try it") is forward-looking work tied to the public developer API. Until that exists, the canonical, authoritative description of the API surface is the typed SDK — the single contract that Fyndow's own web, mobile, and admin apps consume. This page tells you how to read that SDK as a reference and what each domain module covers.

Why the SDK is the reference

Fyndow is headless: every capability lives behind /api/v1, and there is exactly one client contract that everyone uses. The web app, the mobile app, and the admin dashboard are all clients of the same SDK — they are the first clients, not privileged ones (see The Headless-First Thesis). Because of that, the SDK is not a convenience wrapper that can drift from the real API; it is the typed shape of the real API. Reading a module tells you, precisely and without guessing:

• which HTTP method and path an operation uses,
• the input type it expects,
• and the return type it produces.

The SDK is assembled by a single client factory that returns the domain modules listed below.

How to read a module

Each module is a thin, typed mapping from a method name to an HTTP call. For example, the bookings module maps method names directly onto routes:

• create — POST to /bookings
• list — GET to /bookings (paginated)
• getById — GET to /bookings/:id
• updateStatus — PATCH to /bookings/:id/status
• reschedule — PATCH to /bookings/:id/reschedule
• setAvailability — PUT to /scheduling/availability

From this you can read off the live contract without any extra documentation: bookings.create(input) is POST /api/v1/bookings, bookings.getById(id) is GET /api/v1/bookings/:id, and so on. The input and output types are shared across the SDK (or defined and re-exported by the module itself), so the exact field shapes are discoverable by following the type.

Calling the SDK

// configure the SDK once
const api = createSdk({
  baseUrl: "https://<host>/api/v1",      // version lives in the URL
  getHeaders: async () => ({ /* auth */ }),
});

const booking = await api.bookings.getById("bkg_123");

The base URL includes the /api/v1 version prefix (see Versioning & Changelog Policy). Authentication headers differ by client: the web app sends a CSRF token read from a cookie; the mobile app sends a bearer token. The SDK takes a getHeaders callback so each client supplies the right credential.

The shared request/response conventions

A handful of conventions hold across every module, because they are implemented once in the SDK's core client rather than per endpoint:

• Response envelope. The backend wraps responses in { data: ... }. The SDK unwraps non-paginated responses to return the payload directly, and preserves the { data, meta } shape for paginated ones (PaginatedResult<T>).
• Pagination. List endpoints return { data: [...], meta: {...} }; the meta carries paging information.
• Errors. Non-2xx responses throw a typed ApiError carrying statusCode, an error code, a human message, and optional details.
• No content. 204 responses resolve to undefined.
• Credentials. Requests are sent with credentials: "include" so cookie-based auth and the CSRF double-submit pattern work.

Knowing these once means you can read any module without re-learning its plumbing — only its method names, paths, and types differ.

Domain modules

The client factory returns the following domain modules. Each is the reference for its slice of the API; open the named module to see its methods, paths, and types.

Module	Covers
auth	Sign in/up/out, session
users	Profile, preferences, avatar
businesses	Business pages / storefronts
organizations	Organization accounts
services	Service listings (CRUD, pricing)
products	Product catalog, inventory
bookings	Bookings, timeline, availability, time blocks
orders	Cart, checkout, fulfillment
invoices	Invoices, recurring invoices, payment tracking
quotes	Quotes, line items, approval
messaging	Conversations, messages, read receipts
forums	Forums, posts, comments, votes, memberships, moderation
reviews	Mutual reviews and responses
endorsements	Peer / community endorsements
notifications	In-app notifications, preferences, devices
search	Full-text + geo search
payments	Payment onboarding, payment intents, payouts
media	Uploads (presigned URLs)
ai	AI assistant (tool-calling, confirmation flow)
addresses	Saved addresses
credentials	Credential submission / verification
disputes	Dispute lifecycle
calendarSync	External calendar sync
accounting	Accounting export (e.g. invoice export)
portfolio	Portfolio items
announcements	Targeted announcements
digests	Personalized digests, preferences
categories	Category catalog
geo	Geocoding suggestions
issueReports	Issue / bug reports
platform	Admin platform operations (audit, refunds, cancellations)
adminInbox	Admin inbound-email inbox

The factory also exposes a low-level client for raw, custom requests against any path under the version prefix.

Reading payments as a concrete example

To see the convention in practice, the payments module maps connected-account onboarding and charging onto explicit routes:

• POST to /payments/connect/create-account — idempotent connected-account creation
• POST to /payments/connect/onboarding-link — hosted onboarding link
• GET to /payments/connect/status — current onboarding/account status
• GET to /payments/connect/login-link — single-use dashboard login link
• POST to /payments/create-intent — create a payment intent

These line up directly with the money mechanics described in Payments & Payout Timing — the SDK is where the documented behaviour meets the exact endpoint.

What the generated reference will add

A generated reference (the forward-looking deliverable) will add, on top of the SDK, things the SDK alone does not surface: full request/response JSON schemas with examples, error catalogs per endpoint, scope requirements per route, and an interactive console. That work is bound to the same prerequisites as the public API itself — authentication models (API keys / OAuth), scopes, per-key rate limiting, and the multi-tenant isolation audit. Those are detailed in The Public API.

:::note TODO There is no generated, browsable API reference (e.g. an OpenAPI/Swagger site) yet. Until it exists, treat the typed SDK's modules as the canonical endpoint reference. When the generated reference ships, replace this orientation with a direct link to it and keep this page as the conceptual on-ramp. :::