API, MCP et agents

Entrée

En-têtes

• Authorization string

  Jeton de session envoyé sous la forme Bearer <session>.

Aucun corps de requête requis.

Réponse

200 application/json

{
  "session": "OPAQUE_SESSION_KEEP_PRIVATE",
  "expires_in": 7776000
}

• session string · obligatoire

  Jeton privé du client, à conserver pour les appels suivants.

• expires_in integer · obligatoire

  Durée de validité de la session, en secondes.

  Valeur : 7776000

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

• X-Dilem-Case-ID string

  Identifiant conservé pour tous les échanges d’un même dilemme.

  Format technique

  ^[a-zA-Z0-9_-]{1,80}$

Aucun corps de requête requis.

Réponse

200 application/json

{
  "day": "2026-01-01",
  "resets_at": "2026-01-02T00:00:00Z",
  "collective": {
    "completed": 42
  },
  "dilemmas": {
    "used": 1,
    "limit": 20,
    "remaining": 19
  },
  "case": {
    "id": "my-unique-dilemma-id",
    "admitted": true,
    "completed": false
  },
  "voice": {
    "seconds_used": 0,
    "seconds_reserved": 0,
    "seconds_remaining": 1200,
    "seconds_limit": 1200,
    "max_seconds": 60
  },
  "budget": {
    "daily_usd": 5,
    "available": true
  }
}

• day string · obligatoire

  Journée UTC des compteurs.

  Date au format ISO 8601

• resets_at string · obligatoire

  Date et heure du prochain renouvellement des crédits.

  Date et heure au format ISO 8601

• collective object · obligatoire

  Compteur collectif des dilemmes terminés.

  Champs

  • completed integer · obligatoire

    Nombre de dilemmes terminés dans le compteur collectif.

• dilemmas object · obligatoire

  Crédits de dilemme utilisés, disponibles et autorisés.

  Champs

  • used integer · obligatoire

    Crédits déjà utilisés.

    Minimum : 0

  • limit integer · obligatoire

    Plafond de crédits de la politique active.

    Minimum : 0

  • remaining integer · obligatoire

    Crédits encore disponibles.

    Minimum : 0

• case object · obligatoire

  État du dilemme correspondant au Case-ID fourni.

  Champs

  • id string | null · obligatoire

    Case-ID demandé, ou null sans identifiant.

  • admitted boolean · obligatoire

    Indique si ce dilemme a déjà été admis dans le quota.

  • completed boolean · obligatoire

    Indique si une première recommandation a terminé ce dilemme.

• voice object · obligatoire

  Durées de dictée et plafonds, en secondes.

  Champs

  • seconds_used number

    Secondes de dictée déjà consommées.

  • seconds_reserved number

    Secondes temporairement réservées par une capture en cours.

  • seconds_remaining number

    Secondes de dictée encore disponibles.

  • seconds_limit number

    Plafond total de dictée, en secondes.

  • max_seconds number

    Durée maximale d’une capture, en secondes.

• budget object · obligatoire

  Budget financier partagé et disponibilité du service.

  Champs

  • daily_usd number · obligatoire

    Plafond financier quotidien du service, en dollars US.

  • available boolean · obligatoire

    Indique si le budget permet encore des calculs.

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

• X-Dilem-Case-ID string · obligatoire

  Identifiant conservé pour tous les échanges d’un même dilemme.

  Format technique

  ^[a-zA-Z0-9_-]{1,80}$

Corps application/json

{
  "text": "Train or bus for my commute?",
  "language": "en",
  "refinements": [],
  "clarification_version": 2
}

• text string · obligatoire

  Le choix initial, conservé à chaque tour.

  De 1 à 6 000 caractères

• language string · obligatoire

  Langue de l’interface. Les réponses suivent les propos de l’utilisateur.

  Valeurs possibles : "fr", "en", "it", "de", "es", "pt"

• refinements string[]

  Questions et réponses réelles, dans l’ordre chronologique.

  40 éléments maximum · 6 000 caractères maximum par élément · Par défaut : []

• force_decision boolean

  Seulement si l’utilisateur demande une recommandation sans autre question.

  Par défaut : false

• clarification_count integer

  Nombre de réponses aux clarifications.

  De 0 à 20 · Par défaut : 0

• clarification_version integer

  Version du contrat, toujours 2.

  Par défaut : 2 · Valeur : 2

{
  "session": "<session from start_session>",
  "case_id": "my-unique-dilemma-id",
  "text": "Train or car for a weekend trip?",
  "language": "en"
}

Réponse

200 application/json

{
  "type": "clarification",
  "question": "How far is your commute?",
  "choices": [],
  "format": "number",
  "unit": "km",
  "summary": "Train or bus"
}

{
  "type": "result",
  "summary": "Train or bus for my commute?",
  "options": [
    {
      "id": "train",
      "label": "Take the train",
      "description": "Use the direct rail connection.",
      "probability": 0.7
    },
    {
      "id": "bus",
      "label": "Take the bus",
      "description": "Use the bus stop near home.",
      "probability": 0.3
    }
  ],
  "selected": "train",
  "sources": [],
  "result_id": "0123456789abcdef0123456789abcdef"
}

{
  "type": "error",
  "code": "case_completed"
}

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

Corps application/json

{
  "result": {
    "summary": "Train or bus for my commute?",
    "selected": "train",
    "options": [
      {
        "id": "train",
        "label": "Take the train",
        "description": "Use the direct rail connection.",
        "probability": 0.7
      },
      {
        "id": "bus",
        "label": "Take the bus",
        "description": "Use the bus stop near home.",
        "probability": 0.3
      }
    ]
  },
  "language": "en",
  "theme": "light"
}

• result CardResult · obligatoire

  Résultat déjà reçu, à fournir pour produire le PNG.

  Champs

  • summary string · obligatoire

    Synthèse du dilemme.

    De 1 à 6 000 caractères

  • selected string · obligatoire

    Identifiant de l’option recommandée.

    32 caractères maximum

  • options CardOption[] · obligatoire

    Options comparées et informations associées.

    De 2 à 8 éléments

    Champs

    • id string · obligatoire

      Identifiant unique de cette option dans le résultat.

      Format technique

      ^[a-z][a-z0-9_]{0,31}$

    • label string · obligatoire

      Libellé de l’option sur la carte.

      De 1 à 120 caractères

    • description string

      Courte description affichée avec l’option.

      240 caractères maximum · Par défaut : ""

    • probability number · obligatoire

      Poids de préférence, pas une probabilité de réussite.

      De 0 à 1

• language string

  Langue de présentation.

  Valeurs possibles : "fr", "en", "it", "de", "es", "pt" · Par défaut : "fr"

• theme string

  Thème visuel de la carte PNG.

  Valeurs possibles : "light", "dark" · Par défaut : "light"

Réponse

200 image/png

Fichier PNG privé renvoyé en pièce jointe. Le nom du fichier figure dans Content-Disposition.

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

Paramètres du chemin

• result_id string · obligatoire

  Identifiant du résultat appartenant à ce client.

  Format technique

  ^[0-9a-f]{32}$

Aucun corps de requête requis.

Réponse

200 application/json

{
  "result_id": "0123456789abcdef0123456789abcdef",
  "helpful": false,
  "reason": "missing_constraint"
}

• result_id string · obligatoire

  Identifiant du résultat appartenant à ce client.

  Format technique

  ^[0-9a-f]{32}$

• helpful boolean | null · obligatoire

  Avis enregistré, ou null si aucun vote n’a été donné.

• reason null | string · obligatoire

  Motif de l’avis négatif, ou null.

  Valeurs possibles : null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

Corps application/json

{
  "result_id": "0123456789abcdef0123456789abcdef",
  "helpful": false,
  "reason": "missing_constraint"
}

• result_id string · obligatoire

  Identifiant du résultat appartenant à ce client.

  Format technique

  ^[0-9a-f]{32}$

• helpful boolean · obligatoire

  Avis explicite de l’utilisateur sur la réponse.

• reason null | string

  Motif de l’avis négatif, ou null.

  Valeurs possibles : null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

Réponse

200 application/json

{
  "result_id": "0123456789abcdef0123456789abcdef",
  "helpful": false,
  "reason": "missing_constraint"
}

• result_id string · obligatoire

  Identifiant du résultat appartenant à ce client.

  Format technique

  ^[0-9a-f]{32}$

• helpful boolean | null · obligatoire

  Avis enregistré, ou null si aucun vote n’a été donné.

• reason null | string · obligatoire

  Motif de l’avis négatif, ou null.

  Valeurs possibles : null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

{
  "type": "error",
  "code": "case_completed"
}

Entrée

En-têtes

• Authorization string · obligatoire

  Jeton de session envoyé sous la forme Bearer <session>.

Corps application/json

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "kind": "general",
  "message": "Please explain how the recommendation uses my constraints.",
  "email": "",
  "language": "en",
  "source": "agent",
  "version": "unknown",
  "screen": "other",
  "response": null
}

• request_id string · obligatoire

  Identifiant à conserver pour dédupliquer le même envoi.

  Format technique

  ^[0-9a-f]{32}$

• kind string · obligatoire

  Message libre ou signalement d’une réponse.

  Valeurs possibles : "general", "response"

• message string · obligatoire

  Commentaire expressément fourni par l’utilisateur.

  De 5 à 4 000 caractères

• email string · obligatoire

  Adresse de contact, ou chaîne vide.

  254 caractères maximum

• language string · obligatoire

  Langue de présentation.

  Valeurs possibles : "fr", "en", "it", "de", "es", "pt"

• source string · obligatoire

  Point d’entrée à l’origine du message.

  Valeurs possibles : "agent", "menu", "help", "response"

• version string · obligatoire

  SHA de l’application, ou unknown.

  Format technique

  ^[0-9a-f]{40}$|^unknown$

• screen string · obligatoire

  Écran depuis lequel le message est envoyé.

  Valeurs possibles : "home", "clarification", "result", "other"

• response null | ReportedResponse · obligatoire

  Réponse exacte jointe au signalement, sinon null.

  Champs

  null

  null

  Réponse jointe ReportedResponse

  • kind string · obligatoire

    Nature de la réponse jointe au signalement.

    Valeurs possibles : "clarification", "recommendation"

  • text string · obligatoire

    Texte exact de la réponse jointe.

    De 1 à 12 000 caractères

  • reference string · obligatoire

    Référence de la réponse concernée.

    Format technique

    ^[A-Za-z0-9._:-]{1,80}$

Réponse

200 application/json

{
  "ok": true
}

• ok boolean · obligatoire

  Confirme l’enregistrement du message.

  Valeur : true

{
  "type": "error",
  "code": "case_completed"
}