API Reference

Every FastAPI router in backend/app/api/ on origin/main (July 2026), verified against the code — not the OpenAPI-first design intent. Contract-first tooling: backend/scripts/export_openapi.py → frontend/openapi.json → npm run api:generate → frontend/src/api/generated/schema.d.ts. Feature composables call the typed client (frontend/src/api/client.ts), never hand-built fetch.

Endpoint index

The async meal-logging contract

Stable from day 1 regardless of what runs behind it — phase 1 drains the AI job in-process via a BackgroundTask after the 202 response (story R1); phase 2 is SQS + a worker Lambda. The frontend is never touched by that swap.

POST /meals {text, meal_type, log_date?, locale, client_queue_id?}
  → 202 { meal_id, status: "processing", reused: false }
    (LogMeal: consent check → backdate check (≤7 days, no future) → UsageMeter.check_entitlement
     + check_and_reserve → MealLogStore creates draft + ai_jobs row atomically)
    (reused: true short-circuits this — a ≥3×-confirmed MealMemory match returns a complete
     draft instantly with reused=true, zero AI call, and the client can skip polling)

GET  /meals/{id}/draft
  → 200 { ..., confidence_level: "pending" | ..., nutrients: [] | [...] }
    (client polls until confidence_level / nutrients indicate completion)

POST /meals/{id}/save {meal_type?}
  → 200 { meal_id, status: "logged" }
    (SaveMeal: draft→logged, MealSaveStore recomputes daily_summaries atomically —
     RSS/root-sum-square aggregation)

POST /meals/{id}/reestimate {text?, locale, expected_version?}
  → 200 { meal_id, reestimate_count, version, ...new estimate }
    (capped at 1 re-estimate per meal; expected_version guards a stale-edit race)

GET  /meals?date=YYYY-MM-DD
  → 200 [MealView, ...]   ← always open, logged meals only (drafts are invisible here)

POST /meals  (after trial exhausted, no subscription)
  → 402 { detail: "trial_expired" }

Auth / session flow

Social sign-in only — no password ever exists in emealia. Google today (GoogleAuthBoundary, story 7.1a); Apple planned (7.1b) behind the same AuthBoundary shape.

GET  /auth/google/login
  → 302 to Google's consent screen
    (mints state+nonce, stashed in short-lived httpOnly cookies scoped to /auth,
     SameSite=Lax so they survive the cross-site redirect back)

GET  /auth/google/callback?code=&state=
  → verify state (constant-time compare) → SocialSignIn.complete(code, nonce)
      → GoogleAuthBoundary exchanges code for a verified identity
      → AuthUserStore claims-or-creates the users row on (auth_provider, provider_subject)
  → issue session cookie (JwtSessionCodec, HS256, httpOnly, Secure, SameSite=Lax)
  → 302 straight to Today — no interstitial
  (declined/failed/unavailable all redirect calmly to /login?auth=cancelled|failed|unavailable —
   never a raw error page, non-negotiable #6)

POST /auth/logout → 204
  (clears the session cookie only; server-side "sign out everywhere" is planned, story 7.4b)

GET  /auth/session → { authenticated: bool, user_id?: string }
  (non-raising probe for the frontend router guard)

Billing flow

POST /billing/checkout {price_id | interval, locale, success_url, cancel_url}
  → 201 { checkout_url }
    (StartCheckout resolves the market's Stripe price id via BillingCatalogs —
     one catalog per market locale (de-DE, en-US), each with a monthly + annual Stripe price id)

POST /billing/portal {return_url}
  → 201 { portal_url }

POST /billing/webhooks/stripe  (Stripe-signed)
  → 200 { event_id, processed }
    (idempotent — a duplicate event id is a primary-key conflict against
     processed_webhook_events, treated as already-applied)

Tenancy & auth dependency

Every session-scoped endpoint depends on current_user (raises on missing/invalid session) or optional_user (/auth/session only). All queries are scoped to the resolved UserId — no endpoint accepts a caller-supplied user id. See security-hardening skill + backend/app/api/rate_limit.py / security_headers.py for the cross-cutting middleware (not itemized per-route here).