API Overview

Base URL in dev: http://localhost:3001. The live, always-accurate reference is the API's own Scalar page at /docs (spec at /openapi.json, auth endpoints at /api/auth/reference). These pages explain the concepts and flows instead.

Surface

Conventions

• Validation: every body/param is validated with a Zod schema from @repo/shared; failures return 400 { error: "Validation failed", issues: [...] }.
• Errors: always { error: string } with a meaningful status. Unhandled errors become a logged 500.
• Rate limiting: /api/wishlist/* is limited to 10 req/min/IP (in-memory — swap for Redis when the API runs on more than one instance).
• CORS: only origins in CORS_ORIGINS may call /api/* with credentials.
• Sessions: better-auth cookie, sent with credentials: "include".

Adding an endpoint

1. Add/extend schemas in packages/shared/src/.
2. Define a createRoute + handler in the route file (or a new factory in apps/api/src/routes/, mounted in app.ts).
3. Write a test in apps/api/test/ using makeTestApp() — it exercises the real app against in-memory Postgres.
4. The Scalar docs update themselves from the route definition.