API Documentation

This directory contains API documentation for Quinoa.

Where the API is documented

The Quinoa REST API is documented in the product repository, next to the code, so it is updated in the same pull request as the change it describes. This page is the pointer to it.

Document	Location	What it is
API reference	docs/API.md in quinoapp	Human-readable reference: every implemented endpoint with request/response shapes and examples, data models, authentication, known limitations, and proposed future endpoints
OpenAPI contract	docs/openapi.yaml in quinoapp	Machine-readable OpenAPI 3.0.3 contract of the implemented endpoints — use it to generate clients, drive tooling, or give agents structured context
Architecture context	ARCHITECTURE.md in quinoapp	How the API fits into the system: routing, the IStorage layer, the data model
Orientation	Architecture Overview	Condensed map of the system, including the endpoint list by area

Source of truth is the code — server/routes.ts and server/auth.ts. Where a document and the code disagree, the code wins and the document gets fixed.

At a glance

• 15 implemented endpoints, all under the /api prefix.
• Session cookies, not bearer tokens. Every /api/* route requires an authenticated session except GET /api/health, POST /api/auth/login, and POST /api/auth/register.
• JSON in and out, except POST /api/grocery/analyze, which takes multipart/form-data.
• Macros are serialized as strings ("25.5"), not numbers — they are SQL decimals.
• Two error shapes coexist: business routes return { "error": "…" }, auth routes return { "message": "…" }.

docs/API.md also carries a Known limitations section — no role-based authorization, demo data behind the specialist endpoints, a hardcoded targetCalories — worth reading before you build against the API.

Standards

• Use OpenAPI 3.0+ for API specifications
• Include request/response examples
• Document all error codes
• Version all APIs