# 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                                                                        |