Documentation bêta

API ALIM.

ALIM expose une API HTTPS qui reçoit un brief patient anonyme et renvoie une recette cadrée par la base Ciqual 2025 et les recommandations cliniques françaises. Cette doc couvre le périmètre bêta — elle évoluera avec l'authentification dédiée.

Vue d'ensemble

L'API est consommée par :

• Custom GPT ALIM (ChatGPT) — action HTTPS configurée sur cette API ;
• Remote MCP ALIM (Claude, Gemini CLI, Cursor et clients compatibles) — endpoint Streamable HTTP sur /mcp/v1 ;
• Mirabelle, l'agent de démo public sur alim.care — appel orchestré côté serveur ALIM.

L'API est stateless : chaque requête est indépendante, aucune donnée patient n'est conservée au-delà de la réponse, sauf agrégation statistique anonyme.

Base URL : https://alim.care

Authentification

L'authentification par clé Bearer sera obligatoire avant diffusion publique. Format prévu :

Authorization: Bearer alim_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cycle de vie d'une clé :

• générée à l'admission en bêta, transmise par e-mail au praticien après validation manuelle de sa demande sur /configurer/ ;
• personnelle, non transférable ;
• quota par clé (par défaut 20 générations/jour en bêta) ;
• révocable à tout moment par e-mail à alim@holco.co.

MCP Claude, Gemini CLI et clients compatibles

ALIM expose aussi un connecteur Remote MCP pour Claude, Gemini CLI, Cursor et les clients compatibles MCP Streamable HTTP.

POST https://alim.care/mcp/v1

GET https://alim.care/.well-known/mcp.json

Outils exposés : get_alim_account, brief_radar, generate_clinical_recipe, scan_recipe_text, scan_recipe_url, list_saved_recipes, save_generated_recipe, get_saved_recipe, delete_saved_recipe.

• Entrée identique à l'API /api/generate : pathologies, repas, régime, saison, équipement, notes anonymisées.
• Une génération = un repas. Pour petit-déjeuner + déjeuner + dîner, le client doit appeler le tool trois fois.
• Sortie principale pour Claude : presentation_markdown_fr, à afficher sans résumer ni réécrire.
• Sortie structurée : professional_sheet, utile pour PDF, fiche patient, liste de courses et exports.
• Après la recette, afficher le lien pdf_url si le praticien veut l'aperçu imprimable.

Test MCP minimal :

curl -sS https://alim.care/.well-known/mcp.json

curl -sS https://alim.care/mcp/v1 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

POST /api/generate

Génère une recette cadrée à partir d'un brief patient anonyme.

POST https://alim.care/api/generate

Payload

{
  "pathologies": ["diabete_gestationnel", "grossesse"],
  "meal_slot": "dejeuner",
  "diet_type": "vegetarien",
  "season": "ete",
  "equipment": ["plaque", "four"],
  "portions": 1,
  "notes": "Sans crudités à risque."
}

Modèle de réponse

{
  "recipe": {
    "name_fr": "Salade tiède quinoa, pois chiches et œuf dur",
    "portion_g": 462,
    "ingredients": [
      { "name_fr": "Quinoa cuit", "quantity_g": 120, "ciqual_code": "9341" },
      { "name_fr": "Pois chiches cuits", "quantity_g": 90, "ciqual_code": "20347" },
      ...
    ],
    "steps_fr": [
      "Rincer les pois chiches…",
      "Cuire le quinoa…",
      "Servir tiède."
    ]
  },
  "nutrients_per_portion": {
    "energy_kcal":     { "value": 462,  "source": "ciqual", "confidence": "high" },
    "carb_g":          { "value": 52,   "source": "ciqual", "confidence": "high" },
    "sugar_g_total":   { "value": 4,    "source": "ciqual", "confidence": "high" },
    "fiber_g":         { "value": 9,    "source": "ciqual", "confidence": "high" },
    "saturated_fat_g": { "value": 1.8,  "source": "ciqual", "confidence": "high" },
    "salt_g":          { "value": 0.3,  "source": "ciqual", "confidence": "high" },
    "vit_b9_dfe_ug":   { "value": 290,  "source": "ciqual", "confidence": "high" }
  },
  "presentation_markdown_fr": "## Salade tiède quinoa...",
  "pdf_url": "https://alim.care/pdf/?pathologies=...",
  "professional_sheet": {
    "title_fr": "Salade tiède quinoa, pois chiches et œuf dur",
    "nutrition_panel_per_portion": [],
    "ingredients_detailed_fr": [],
    "preparation_steps_fr": [],
    "export_blocks": {
      "shopping_list_fr": [],
      "substitutions_fr": [],
      "serving_tips_fr": []
    }
  },
  "rules": [
    {
      "id": "dg_glucides_meal_max",
      "rationale_fr": "Glucides cadrés pour le repas (diabète gestationnel).",
      "status": "passed"
    },
    {
      "id": "grossesse_toxoplasmose_legumes",
      "rationale_fr": "Légumes cuits ou bien lavés.",
      "status": "passed"
    }
  ],
  "sources": [
    { "fr": "ANSES — Q/R Toxoplasmose", "pdf_page": 2, "url": "https://www.anses.fr/..." },
    { "fr": "EFSA — Folate DRV",        "pdf_page": null, "url": "https://www.efsa.europa.eu/..." }
  ],
  "warnings": [
    "Outil d'aide à la formulation, réservé aux professionnels — ne remplace pas le jugement clinique."
  ]
}

Refus hors périmètre

Si le brief sort du périmètre couvert (par ex. insuffisance rénale), ou si la validation déterministe échoue, l'API renvoie un statut 422 Unprocessable Entity avec une charge utile refused :

{
  "refused": {
    "reason_fr": "ALIM v0 couvre seulement les deux démos publiques : diabète T2 + HTA, ou grossesse + diabète gestationnel."
  },
  "warnings": [
    "Outil d'aide à la formulation, réservé aux professionnels — ne remplace pas le jugement clinique."
  ]
}

Tout refus est tracé et n'apparaît jamais sous la forme d'une recette improvisée. C'est la garantie principale du moteur.

Règles PII

Côté notes : décrire le profil anonymement — pathologie, âge approximatif, contraintes alimentaires, équipement, saison. Pas d'identifiant.

Côté Mirabelle (démo publique), un préfiltre côté serveur rejette automatiquement tout message contenant une signature PII détectée (e-mail, téléphone FR, date complète, NIR). Le même préfiltre sera étendu aux clients authentifiés.

Périmètre bêta

L'API V0 couvre deux situations cliniques :

• Diabète T2 + HTA — adulte, fonction rénale normale, hors grossesse ;
• Grossesse + diabète gestationnel — hors complication aiguë.

L'insuffisance rénale (CKD) est explicitement hors périmètre. Toute mention déclenche un refus traçable.

Santé service

GET https://alim.care/api/health

{ "ok": true, "service": "alim", "version": "0.1.0" }

Changelog

• 2026-05 : V0 — moteur déterministe stateless, deux situations couvertes, refus traçable hors périmètre. Endpoint POST /api/generate sans authentification pour la phase bêta restreinte.
• À venir : authentification Bearer, quota par clé, journaux anonymes, migration vers /api/v1/generate.