Cibello-app/docs/08-api-referens.md

Del 8 – API-referens (v1)

Bas: https://<apiDomain> (ur brand.config.json) (dev: http://localhost:4000). All data JSON. Auth: Authorization: Bearer <accessToken> (JWT, 15 min) + roterande refresh-token. Fel: { "error": { code, message, details?, correlationId } }. Rate limit 300/min (auth-endpoints 10/min). Live-lista över endpoints: GET /docs.

Auth

Metod	Path	Beskrivning
POST	/v1/auth/register	Skapa konto; startar 7-dagars trial; returnerar tokens
POST	/v1/auth/login	Logga in
POST	/v1/auth/refresh	Rotera refresh-token (återanvändning → hela familjen revokeras)
POST	/v1/auth/logout	Revokera alla sessioner
POST	/v1/auth/change-password	Byt lösenord (loggar ut övriga enheter)

Användare & profil (§6, §21, §32–33, §56)

| GET/PATCH | /v1/me | Konto, precisionMode, aktivt hushåll | | GET/PATCH | /v1/me/health-profile | Hälsodata (separat domän) | | GET/PATCH | /v1/me/preferences | Mål, kost, allergier, favoritkök, budget, utrustning | | POST | /v1/me/onboarding | Allt-i-ett: profil + preferenser + hushållsval | | GET/PUT | /v1/me/consents | Separata samtycken | | GET | /v1/me/daily-targets | Deterministiska dagsmål + beräkningsgrund | | GET | /v1/me/entitlements | Plan, kvoter, signerad offline-token (§44/§47) | | GET | /v1/me/export | GDPR-export | | DELETE | /v1/me | GDPR-radering | | GET | /v1/me/memory | "Vad appen vet om mig" (sektioner per minnestyp) | | PATCH/DELETE | /v1/me/memory/:id | Rätta (→ user_stated, verifierad) / radera post | | DELETE | /v1/me/memory | Radera allt minne | | POST | /v1/me/memory/pause-all | Pausa/återuppta allt |

Hushåll (§7–8)

| GET/POST | /v1/households | Mina hushåll / skapa (auto: kyl, frys, skafferi) | | GET/PATCH | /v1/households/:id | Detalj med medlemmar+platser (ALDRIG medlemmars hälsodata) | | POST | /v1/households/join | Gå med via inviteCode (plangräns kontrolleras) | | PATCH/DELETE | /v1/households/:id/members/:userId | Roll/portionsfaktor / ta bort | | POST/PATCH | /v1/households/:id/storage-locations[/:locationId] | Platser |

Lager – Food Twin (§8–13)

| GET | /v1/inventory | Lager med expiry-klassning; filter: plats/status/sök | | GET | /v1/inventory/expiring | "Använd snart", sorterat mest bråttom först | | POST | /v1/inventory/items | Lägg till (+purchase-transaktion, dubblettkandidater i svaret) | | PATCH/DELETE | /v1/inventory/items/:id | Ändra (mängd → adjust-transaktion) / arkivera | | POST | /v1/inventory/items/:id/transactions | consume/discard/adjust… (discard sätter value_minor) | | GET | /v1/inventory/items/:id/transactions | Historik | | GET | /v1/ingredients?search= | Kanonisk ingrediens-sök (alias-medveten) |

Skanning (§10–12, §50)

| POST | /v1/scans | Skapa jobb; AI-typer drar kvot + ger presignade upload-URL:er; barcode svarar direkt | | POST | /v1/scans/:id/start | Lägg på kön (worker → AAMOS) | | GET | /v1/scans/:id | Status + kontraktvaliderat resultat | | POST | /v1/scans/:id/confirm | Godkänn/ändra/avvisa/lägg till → lager + ai_corrections | | GET | /v1/scans | Mina senaste skanningar |

Recept (§14–20)

| GET | /v1/recipes | Sök/filter: kök, måltid, taggar, tid, kcal, protein, kostnad, svårighet, exkl. allergener | | GET | /v1/recipes/:id | Detalj + personlig säkerhetsanalys + varianter + mitt betyg | | GET | /v1/recipes/:id/scaled?portions= | Skalade mängder | | POST | /v1/recipes/:id/cook | "Jag lagade": FEFO-lagerdrag, måltider per ätare, matlådor, events | | POST | /v1/recipes/:id/rate | Betyg + feedbacktaggar (→ smaksignaler) | | POST/DELETE | /v1/recipes/:id/favorite | Favorit | | GET | /v1/recipes/favorites/mine | Mina favoriter | | POST | /v1/recipes | Användarrecept: strukturerat eller fritext (AAMOS-strukturering) → moderering (§35) | | GET | /v1/substitutions?fromIngredientId=&context= | Substitutionsförslag (§20) |

Rekommendationer (§18–19)

| GET | /v1/recommendations/what-to-eat | Kärn-endpointen: craving, persons, maxMinutes, maxCost; svarar med matlådor-först + rankade förslag med whySv, saknade varor, utgående varor |

Måltider & matlådor (§22–24)

| POST | /v1/meals | Logga (recept/produkt/foto-intervall/manuell – aldrig AI-påhitt) | | GET | /v1/meals/day?date= | Min dag: måltider + summering mot mål | | GET | /v1/meals/recent | Snabb återloggning | | DELETE | /v1/meals/:id | Ta bort | | GET/POST | /v1/meal-boxes | Matlådor | | POST | /v1/meal-boxes/:id/consume | Ät (drar portioner, loggar måltid) | | POST | /v1/meal-boxes/:id/discard | Släng |

Planering & inköp (§25–27)

| GET | /v1/week-plans | Planer med poster | | POST | /v1/week-plans/generate | Generera (premium; asynkront via worker) | | PATCH | /v1/week-plans/:id/entries/:entryId | Ändra/skippa (auto-omplanering med förklaring) | | POST | /v1/week-plans/:id/activate | Aktivera | | GET/POST | /v1/shopping-lists | Listor / skapa (generateFromPlan drar av lagret) | | GET | /v1/shopping-lists/:id | Lista sorterad per avdelning + prissumma | | POST/PATCH/DELETE | /v1/shopping-lists/:id/items[/:itemId] | Rader (auto-merge per ingrediens) | | POST | /v1/shopping-lists/:id/complete | Bockade varor → lagret |

Budget (§26)

| GET | /v1/budget/summary | Vecka/månad: inköp, svinnvärde, kostnad/portion |

Prenumerationer (§45–47)

| POST | /v1/subscriptions/verify | Verifiera Apple/Google-köp (backend = sanningen) | | POST | /v1/subscriptions/restore | Återställ-köp-hänvisning | | POST | /v1/subscriptions/webhooks/apple | App Store Server Notifications (rå → kö) | | POST | /v1/subscriptions/webhooks/google | Play RTDN (rå → kö) |

Community (§35–38)

| GET | /v1/creators/:id | Creatorprofil (respekterar visibility) | | POST/DELETE | /v1/creators/:id/follow | Följ | | GET | /v1/rankings/:kind | most-cooked/top-rated/budget/protein (flagga; aldrig vikt/kalorier) |

Admin (§57) – kräver admin-roll, auditloggas

users · moderation/recipes (kö + approve/reject/request_changes) · flags (PUT med rollout) · subscriptions (+grant) · jobs/overview · system/health · audit-logs · ai/corrections · ai/eval-runs

Infra

GET /healthz · GET /readyz · GET /docs (endpointkatalog)

i18n-endpoints (M2–M6)

Metod	Path	Beskrivning
GET	/v1/me/locale-preferences	Användarens språk/region/mått/valuta (SE-defaults)
PATCH	/v1/me/locale-preferences	Uppdatera locale-preferenser
GET	/v1/i18n/units?languageTag=	Enhetsetiketter per språk ur unit_translations
GET	/v1/i18n/nutrition-profile?region=	Näringsvisning + allergenframhävning per marknad (EU-fallback)
POST	/admin/v1/recipes/:id/translate	Beställ AI-utkast för språk (TRANSLATE_RECIPE-jobb)
GET	/admin/v1/recipes/:id/translations	Lista översättningar med verifieringsresultat
POST	/admin/v1/recipes/:id/translations/:languageTag	publish / in_review / back_to_draft (+ redaktionell rättning)

Recept- och ingrediens-svar bär language + upplösta fält (title, name, instruction …) på användarens språk med svensk källa som fallback. Alla belopp i svar är minor units; budget/summeringar bär currency.

Lösenordsåterställning

Metod	Path	Beskrivning
POST	/v1/auth/forgot-password	Begär återställningsmejl. Svarar ALLTID {ok:true} (anti-enumeration). Token: 32 slumpbytes, sha256-hashad i DB, 30 min TTL, engångs
POST	/v1/auth/reset-password	Token + nytt lösenord. Loggar ut ALLA sessioner. Auditloggas