API, MCP and agents

Input

Headers

• Authorization string

  Session token sent as Bearer <session>.

No request body required.

Response

200 application/json

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

• session string · required

  Private client token to retain for subsequent calls.

• expires_in integer · required

  Session validity period, in seconds.

  Value: 7776000

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

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

• X-Dilem-Case-ID string

  Keep this identifier for every turn of the same dilemma.

  Technical format

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

No request body required.

Response

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 · required

  UTC day of the counters.

  ISO 8601 date

• resets_at string · required

  Date and time of the next credit reset.

  ISO 8601 date and time

• collective object · required

  Shared count of completed dilemmas.

  Fields

  • completed integer · required

    Number of completed dilemmas in the shared counter.

• dilemmas object · required

  Used, remaining and allowed dilemma credits.

  Fields

  • used integer · required

    Credits already used.

    Minimum: 0

  • limit integer · required

    Credit limit from the active policy.

    Minimum: 0

  • remaining integer · required

    Credits still available.

    Minimum: 0

• case object · required

  State of the dilemma identified by the supplied Case-ID.

  Fields

  • id string | null · required

    Requested Case-ID, or null when none was supplied.

  • admitted boolean · required

    Whether this dilemma has already been admitted under the quota.

  • completed boolean · required

    Whether a first recommendation completed this dilemma.

• voice object · required

  Dictation durations and limits, in seconds.

  Fields

  • seconds_used number

    Dictation seconds already used.

  • seconds_reserved number

    Seconds temporarily reserved by an active capture.

  • seconds_remaining number

    Dictation seconds still available.

  • seconds_limit number

    Total dictation limit, in seconds.

  • max_seconds number

    Maximum capture duration, in seconds.

• budget object · required

  Shared financial budget and service availability.

  Fields

  • daily_usd number · required

    Daily service budget limit, in US dollars.

  • available boolean · required

    Whether the budget still allows calculations.

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

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

• X-Dilem-Case-ID string · required

  Keep this identifier for every turn of the same dilemma.

  Technical format

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

Body application/json

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

• text string · required

  Initial choice, retained on every turn.

  1–6 000 characters

• language string · required

  Interface language. Replies follow the user’s own words.

  Allowed values: "fr", "en", "it", "de", "es", "pt"

• refinements string[]

  Actual questions and answers in chronological order.

  Up to 40 items · Up to 6 000 characters per item · Default: []

• force_decision boolean

  Only when the user requests a recommendation without further questions.

  Default: false

• clarification_count integer

  Number of clarification answers.

  0–20 · Default: 0

• clarification_version integer

  Contract version, always 2.

  Default: 2 · Value: 2

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

Response

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"
}

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

Body 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 · required

  Previously received result to supply for PNG rendering.

  Fields

  • summary string · required

    Summary of the dilemma.

    1–6 000 characters

  • selected string · required

    Identifier of the recommended option.

    Up to 32 characters

  • options CardOption[] · required

    Compared options and associated information.

    2–8 items

    Fields

    • id string · required

      Unique identifier of this option within the result.

      Technical format

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

    • label string · required

      Option label on the card.

      1–120 characters

    • description string

      Short description shown with the option.

      Up to 240 characters · Default: ""

    • probability number · required

      Preference weight, not a probability of success.

      0–1

• language string

  Presentation language.

  Allowed values: "fr", "en", "it", "de", "es", "pt" · Default: "fr"

• theme string

  Visual theme of the PNG card.

  Allowed values: "light", "dark" · Default: "light"

Response

200 image/png

Private PNG attachment. Its filename is returned in Content-Disposition.

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

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

Path parameters

• result_id string · required

  Identifier of a result owned by this client.

  Technical format

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

No request body required.

Response

200 application/json

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

• result_id string · required

  Identifier of a result owned by this client.

  Technical format

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

• helpful boolean | null · required

  Recorded vote, or null when no vote was given.

• reason null | string · required

  Reason for a negative vote, or null.

  Allowed values: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

Body application/json

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

• result_id string · required

  Identifier of a result owned by this client.

  Technical format

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

• helpful boolean · required

  User’s explicit vote on the response.

• reason null | string

  Reason for a negative vote, or null.

  Allowed values: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

Response

200 application/json

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

• result_id string · required

  Identifier of a result owned by this client.

  Technical format

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

• helpful boolean | null · required

  Recorded vote, or null when no vote was given.

• reason null | string · required

  Reason for a negative vote, or null.

  Allowed values: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Input

Headers

• Authorization string · required

  Session token sent as Bearer <session>.

Body 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 · required

  Identifier to retain for deduplicating the same submission.

  Technical format

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

• kind string · required

  General message or report of a response.

  Allowed values: "general", "response"

• message string · required

  Comment expressly provided by the user.

  5–4 000 characters

• email string · required

  Contact address, or an empty string.

  Up to 254 characters

• language string · required

  Presentation language.

  Allowed values: "fr", "en", "it", "de", "es", "pt"

• source string · required

  Entry point from which the message originated.

  Allowed values: "agent", "menu", "help", "response"

• version string · required

  Application SHA, or unknown.

  Technical format

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

• screen string · required

  Screen from which the message is sent.

  Allowed values: "home", "clarification", "result", "other"

• response null | ReportedResponse · required

  Exact response attached to the report, otherwise null.

  Fields

  null

  null

  Attached response ReportedResponse

  • kind string · required

    Kind of response attached to the report.

    Allowed values: "clarification", "recommendation"

  • text string · required

    Exact text of the attached response.

    1–12 000 characters

  • reference string · required

    Reference of the response concerned.

    Technical format

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

Response

200 application/json

{
  "ok": true
}

• ok boolean · required

  Confirms the message was recorded.

  Value: true

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