# Private scan memory and corrections

FitVete can remember cloud photo and Nutrition Facts label results privately for your developer account. This reduces repeated provider calls and lets an explicit correction improve an identical rescan. It does not automatically train a vision model.

## Save, retrieve, correct, forget

1. Send an image to `POST /v1/nutrition-from-photo` or `POST /v1/nutrition-label` using a direct `x-api-key`.
2. Check `scan_saved`. When true, store `scan_id`, `scan_revision`, and `scan_expires_at` in your server-side record for the end user who submitted it. A storage outage returns 503 for direct developer scans; a successful direct scan always has a saved identity.
3. Show the estimate for review. If the user explicitly edits it, submit complete corrected food name, calories, protein, carbohydrate, and fat totals. Do not treat an unchanged confirmation as independent evidence.
4. Read the latest result with `GET /v1/scans/{id}`. A stale feedback revision returns `409`; fetch and review the latest version before retrying.
5. Delete it with `DELETE /v1/scans/{id}`. A missing, expired, or other-account scan returns 404; this does not remove separately saved diary entries.

```bash
curl 'https://auth.fitvete.com/functions/v1/food-api/v1/scans/YOUR_SCAN_ID/feedback' \
  -H "x-api-key: $FITVETE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "scan_revision": 0,
    "correction": {
      "name": "Cooked rice with chicken",
      "calories": 520,
      "protein_g": 40,
      "carbs_g": 60,
      "fat_g": 13
    },
    "contribute_to_training": false
  }'
```

The three management operations cost **zero points**, even after your daily quota is exhausted. A valid active key and per-minute limits still apply. Photo/label requests retain their normal 10-point cost, including repeated scans. RapidAPI requests do not receive durable scan IDs; use a direct developer key for the correction workflow.

## Accuracy and reuse

On a new photo, vision identifies food and estimates edible gram portions. When every item resolves in FitVete's reference corpus, those portions determine the nutrient calculation and an additional nutrition-provider call is avoided. Unresolved foods return 422 rather than model-generated nutrition. Vision identifies foods and portions; reference records supply calories and nutrients. Portion estimates remain uncertain.

`POST /v1/nutrition-from-photo` is deliberately strict: it answers only when every visible food is priced from reference data, and otherwise refuses. This differs on purpose from the consumer FitVete app, which since 1.14.2 returns a reviewable low-confidence estimate with a `review_reason` explaining what to check instead of asking the user to retake the photo. If your product needs that behaviour, build it on top of the 422 — the API will not silently substitute a model guess for reference nutrition.

Memory matches the **same image bytes** within the same developer account, for up to 30 days from creation. A new angle, crop, or re-encoding is a new image. A repeat returns `source: "scan-memory"` or `"user-correction"`. Raw photos are not stored in scan memory. Corrected totals replace the original totals; previous micronutrients are cleared to avoid retaining inconsistent numbers. Corrections are labeled as user-provided, not independently verified.

Use the scan's original whole-meal basis for corrections. Choosing to eat half of a correctly estimated meal is a diary serving choice, not a correction to the image's total nutrition.

## Privacy and optional contribution

Your API key authorizes your **developer account**. Enforce your own end-user access checks on your server before returning a scan, accepting a correction, or deleting it. Never expose the developer key to an app client. Scans belonging to different developer accounts cannot be retrieved or corrected by another account.

Private corrections need no shared-learning consent. Only if a user explicitly agrees, send `contribute_to_training: true` and `consent_version: "scan-facts-v1"`. Suggested clear disclosure:

> Allow FitVete to review these corrected food facts for nutrition-engine evaluation. This is optional. Raw images and account identifiers are excluded from exports. The facts expire after 30 days and you can withdraw before future exports.

Permission must be voluntary and specific to the correction. Do not preselect it, infer it from use of your app, or include personal information in food names. Contributions require a separate human review before export. This release has no automated model-training job or public-corpus promotion. The consent does not authorize raw-image training or indefinite dataset retention.

To withdraw, resubmit the current corrected totals with the latest `scan_revision` and `contribute_to_training: false`, or delete the scan. Both immediately remove future export eligibility. Account deletion cascades to this memory. Retrieval and export stop at expiry; hourly bounded cleanup removes expired records. Saved diary photos and records are managed separately.