API, MCP und Agenten

Eingabe

Header

• Authorization string

  Sitzungstoken im Format Bearer <session>.

Kein Anfrageinhalt erforderlich.

Antwort

200 application/json

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

• session string · erforderlich

  Privates Client-Token für nachfolgende Aufrufe.

• expires_in integer · erforderlich

  Gültigkeitsdauer der Sitzung in Sekunden.

  Wert: 7776000

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

• X-Dilem-Case-ID string

  Diese Kennung für alle Schritte desselben Dilemmas beibehalten.

  Technisches Format

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

Kein Anfrageinhalt erforderlich.

Antwort

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

  UTC-Tag der Zähler.

  Datum im ISO-8601-Format

• resets_at string · erforderlich

  Datum und Uhrzeit der nächsten Guthabenerneuerung.

  Datum und Uhrzeit im ISO-8601-Format

• collective object · erforderlich

  Gemeinsamer Zähler abgeschlossener Dilemmas.

  Felder

  • completed integer · erforderlich

    Anzahl abgeschlossener Dilemmas im gemeinsamen Zähler.

• dilemmas object · erforderlich

  Verbrauchtes, verbleibendes und erlaubtes Dilemma-Guthaben.

  Felder

  • used integer · erforderlich

    Bereits verbrauchtes Guthaben.

    Minimum: 0

  • limit integer · erforderlich

    Guthabenlimit der aktiven Richtlinie.

    Minimum: 0

  • remaining integer · erforderlich

    Noch verfügbares Guthaben.

    Minimum: 0

• case object · erforderlich

  Status des durch die Case-ID bezeichneten Dilemmas.

  Felder

  • id string | null · erforderlich

    Angeforderte Case-ID oder null ohne Kennung.

  • admitted boolean · erforderlich

    Ob dieses Dilemma bereits im Kontingent zugelassen wurde.

  • completed boolean · erforderlich

    Ob eine erste Empfehlung dieses Dilemma abgeschlossen hat.

• voice object · erforderlich

  Diktierdauer und Grenzen in Sekunden.

  Felder

  • seconds_used number

    Bereits verbrauchte Diktiersekunden.

  • seconds_reserved number

    Durch eine laufende Aufnahme vorübergehend reservierte Sekunden.

  • seconds_remaining number

    Noch verfügbare Diktiersekunden.

  • seconds_limit number

    Gesamtes Diktierlimit in Sekunden.

  • max_seconds number

    Maximale Aufnahmedauer in Sekunden.

• budget object · erforderlich

  Gemeinsames Finanzbudget und Verfügbarkeit des Dienstes.

  Felder

  • daily_usd number · erforderlich

    Tägliches Finanzlimit des Dienstes in US-Dollar.

  • available boolean · erforderlich

    Ob das Budget weitere Berechnungen zulässt.

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

• X-Dilem-Case-ID string · erforderlich

  Diese Kennung für alle Schritte desselben Dilemmas beibehalten.

  Technisches Format

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

Anfrageinhalt application/json

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

• text string · erforderlich

  Ursprüngliche Wahl bei jedem Aufruf beibehalten.

  1–6 000 Zeichen

• language string · erforderlich

  Sprache der Oberfläche. Antworten folgen den Worten des Nutzers.

  Mögliche Werte: "fr", "en", "it", "de", "es", "pt"

• refinements string[]

  Echte Fragen und Antworten in zeitlicher Reihenfolge.

  Höchstens 40 Einträge · Höchstens 6 000 Zeichen pro Eintrag · Standard: []

• force_decision boolean

  Nur wenn der Nutzer eine Empfehlung ohne weitere Fragen verlangt.

  Standard: false

• clarification_count integer

  Anzahl beantworteter Rückfragen.

  0–20 · Standard: 0

• clarification_version integer

  Vertragsversion, immer 2.

  Standard: 2 · Wert: 2

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

Antwort

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

Anfrageinhalt 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 · erforderlich

  Bereits erhaltenes Ergebnis für die PNG-Erstellung.

  Felder

  • summary string · erforderlich

    Zusammenfassung des Dilemmas.

    1–6 000 Zeichen

  • selected string · erforderlich

    Kennung der empfohlenen Option.

    Höchstens 32 Zeichen

  • options CardOption[] · erforderlich

    Verglichene Optionen mit zugehörigen Angaben.

    2–8 Einträge

    Felder

    • id string · erforderlich

      Eindeutige Kennung dieser Option im Ergebnis.

      Technisches Format

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

    • label string · erforderlich

      Bezeichnung der Option auf der Karte.

      1–120 Zeichen

    • description string

      Kurze Beschreibung zur Option.

      Höchstens 240 Zeichen · Standard: ""

    • probability number · erforderlich

      Präferenzgewicht, keine Erfolgswahrscheinlichkeit.

      0–1

• language string

  Anzeigesprache.

  Mögliche Werte: "fr", "en", "it", "de", "es", "pt" · Standard: "fr"

• theme string

  Darstellungsthema der PNG-Karte.

  Mögliche Werte: "light", "dark" · Standard: "light"

Antwort

200 image/png

Privater PNG-Anhang. Der Dateiname steht in Content-Disposition.

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

Pfadparameter

• result_id string · erforderlich

  Kennung eines diesem Client gehörenden Ergebnisses.

  Technisches Format

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

Kein Anfrageinhalt erforderlich.

Antwort

200 application/json

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

• result_id string · erforderlich

  Kennung eines diesem Client gehörenden Ergebnisses.

  Technisches Format

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

• helpful boolean | null · erforderlich

  Gespeicherte Bewertung oder null ohne Bewertung.

• reason null | string · erforderlich

  Grund einer negativen Bewertung oder null.

  Mögliche Werte: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

Anfrageinhalt application/json

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

• result_id string · erforderlich

  Kennung eines diesem Client gehörenden Ergebnisses.

  Technisches Format

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

• helpful boolean · erforderlich

  Ausdrückliche Bewertung der Antwort durch den Nutzer.

• reason null | string

  Grund einer negativen Bewertung oder null.

  Mögliche Werte: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

Antwort

200 application/json

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

• result_id string · erforderlich

  Kennung eines diesem Client gehörenden Ergebnisses.

  Technisches Format

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

• helpful boolean | null · erforderlich

  Gespeicherte Bewertung oder null ohne Bewertung.

• reason null | string · erforderlich

  Grund einer negativen Bewertung oder null.

  Mögliche Werte: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Eingabe

Header

• Authorization string · erforderlich

  Sitzungstoken im Format Bearer <session>.

Anfrageinhalt 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 · erforderlich

  Kennung zur Deduplizierung derselben Übermittlung.

  Technisches Format

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

• kind string · erforderlich

  Allgemeine Nachricht oder Meldung zu einer Antwort.

  Mögliche Werte: "general", "response"

• message string · erforderlich

  Vom Nutzer ausdrücklich übermittelter Kommentar.

  5–4 000 Zeichen

• email string · erforderlich

  Kontaktadresse oder leere Zeichenfolge.

  Höchstens 254 Zeichen

• language string · erforderlich

  Anzeigesprache.

  Mögliche Werte: "fr", "en", "it", "de", "es", "pt"

• source string · erforderlich

  Einstiegspunkt der Nachricht.

  Mögliche Werte: "agent", "menu", "help", "response"

• version string · erforderlich

  SHA der Anwendung oder unknown.

  Technisches Format

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

• screen string · erforderlich

  Ansicht, aus der die Nachricht gesendet wird.

  Mögliche Werte: "home", "clarification", "result", "other"

• response null | ReportedResponse · erforderlich

  Der Meldung beigefügte exakte Antwort, sonst null.

  Felder

  null

  null

  Beigefügte Antwort ReportedResponse

  • kind string · erforderlich

    Art der einer Meldung beigefügten Antwort.

    Mögliche Werte: "clarification", "recommendation"

  • text string · erforderlich

    Exakter Text der beigefügten Antwort.

    1–12 000 Zeichen

  • reference string · erforderlich

    Referenz der betreffenden Antwort.

    Technisches Format

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

Antwort

200 application/json

{
  "ok": true
}

• ok boolean · erforderlich

  Bestätigt die Speicherung der Nachricht.

  Wert: true

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