API, MCP e agenti

Input

Intestazioni

• Authorization string

  Token di sessione inviato come Bearer <session>.

Nessun corpo della richiesta richiesto.

Risposta

200 application/json

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

• session string · obbligatorio

  Token privato del client, da conservare per le chiamate successive.

• expires_in integer · obbligatorio

  Durata della sessione, in secondi.

  Valore: 7776000

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

Input

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

• X-Dilem-Case-ID string

  Conserva questo identificativo per tutti i turni dello stesso dilemma.

  Formato tecnico

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

Nessun corpo della richiesta richiesto.

Risposta

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

  Giorno UTC dei contatori.

  Data ISO 8601

• resets_at string · obbligatorio

  Data e ora del prossimo rinnovo dei crediti.

  Data e ora ISO 8601

• collective object · obbligatorio

  Contatore collettivo dei dilemmi completati.

  Campi

  • completed integer · obbligatorio

    Numero di dilemmi completati nel contatore collettivo.

• dilemmas object · obbligatorio

  Crediti dei dilemmi usati, disponibili e consentiti.

  Campi

  • used integer · obbligatorio

    Crediti già utilizzati.

    Minimo: 0

  • limit integer · obbligatorio

    Limite di crediti della politica attiva.

    Minimo: 0

  • remaining integer · obbligatorio

    Crediti ancora disponibili.

    Minimo: 0

• case object · obbligatorio

  Stato del dilemma identificato dal Case-ID fornito.

  Campi

  • id string | null · obbligatorio

    Case-ID richiesto, oppure null se non fornito.

  • admitted boolean · obbligatorio

    Indica se il dilemma è già stato ammesso nella quota.

  • completed boolean · obbligatorio

    Indica se una prima raccomandazione ha concluso il dilemma.

• voice object · obbligatorio

  Durate e limiti della dettatura, in secondi.

  Campi

  • seconds_used number

    Secondi di dettatura già consumati.

  • seconds_reserved number

    Secondi temporaneamente riservati da una cattura in corso.

  • seconds_remaining number

    Secondi di dettatura ancora disponibili.

  • seconds_limit number

    Limite totale di dettatura, in secondi.

  • max_seconds number

    Durata massima di una cattura, in secondi.

• budget object · obbligatorio

  Budget economico condiviso e disponibilità del servizio.

  Campi

  • daily_usd number · obbligatorio

    Limite del budget giornaliero del servizio, in dollari USA.

  • available boolean · obbligatorio

    Indica se il budget consente ancora calcoli.

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

Input

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

• X-Dilem-Case-ID string · obbligatorio

  Conserva questo identificativo per tutti i turni dello stesso dilemma.

  Formato tecnico

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

Corpo application/json

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

• text string · obbligatorio

  Scelta iniziale, mantenuta a ogni turno.

  Da 1 a 6 000 caratteri

• language string · obbligatorio

  Lingua dell’interfaccia. Le risposte seguono le parole dell’utente.

  Valori ammessi: "fr", "en", "it", "de", "es", "pt"

• refinements string[]

  Domande e risposte reali in ordine cronologico.

  Fino a 40 elementi · Fino a 6 000 caratteri per elemento · Predefinito: []

• force_decision boolean

  Solo se l’utente chiede una raccomandazione senza altre domande.

  Predefinito: false

• clarification_count integer

  Numero di risposte ai chiarimenti.

  Da 0 a 20 · Predefinito: 0

• clarification_version integer

  Versione del contratto, sempre 2.

  Predefinito: 2 · Valore: 2

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

Risposta

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

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

Corpo 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 · obbligatorio

  Risultato già ricevuto, da fornire per generare il PNG.

  Campi

  • summary string · obbligatorio

    Sintesi del dilemma.

    Da 1 a 6 000 caratteri

  • selected string · obbligatorio

    Identificativo dell’opzione raccomandata.

    Fino a 32 caratteri

  • options CardOption[] · obbligatorio

    Opzioni confrontate e informazioni associate.

    Da 2 a 8 elementi

    Campi

    • id string · obbligatorio

      Identificativo univoco dell’opzione nel risultato.

      Formato tecnico

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

    • label string · obbligatorio

      Etichetta dell’opzione sulla scheda.

      Da 1 a 120 caratteri

    • description string

      Breve descrizione mostrata con l’opzione.

      Fino a 240 caratteri · Predefinito: ""

    • probability number · obbligatorio

      Peso di preferenza, non probabilità di successo.

      Da 0 a 1

• language string

  Lingua di presentazione.

  Valori ammessi: "fr", "en", "it", "de", "es", "pt" · Predefinito: "fr"

• theme string

  Tema visivo della scheda PNG.

  Valori ammessi: "light", "dark" · Predefinito: "light"

Risposta

200 image/png

Allegato PNG privato. Il nome del file è restituito in Content-Disposition.

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

Input

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

Parametri del percorso

• result_id string · obbligatorio

  Identificativo del risultato appartenente a questo client.

  Formato tecnico

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

Nessun corpo della richiesta richiesto.

Risposta

200 application/json

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

• result_id string · obbligatorio

  Identificativo del risultato appartenente a questo client.

  Formato tecnico

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

• helpful boolean | null · obbligatorio

  Voto registrato, oppure null se non espresso.

• reason null | string · obbligatorio

  Motivo di un voto negativo, oppure null.

  Valori ammessi: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Input

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

Corpo application/json

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

• result_id string · obbligatorio

  Identificativo del risultato appartenente a questo client.

  Formato tecnico

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

• helpful boolean · obbligatorio

  Valutazione esplicita dell’utente sulla risposta.

• reason null | string

  Motivo di un voto negativo, oppure null.

  Valori ammessi: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

Risposta

200 application/json

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

• result_id string · obbligatorio

  Identificativo del risultato appartenente a questo client.

  Formato tecnico

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

• helpful boolean | null · obbligatorio

  Voto registrato, oppure null se non espresso.

• reason null | string · obbligatorio

  Motivo di un voto negativo, oppure null.

  Valori ammessi: null, "misunderstood", "missing_constraint", "too_many_questions", "too_vague"

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

Input

Intestazioni

• Authorization string · obbligatorio

  Token di sessione inviato come Bearer <session>.

Corpo 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 · obbligatorio

  Identificativo da conservare per deduplicare lo stesso invio.

  Formato tecnico

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

• kind string · obbligatorio

  Messaggio libero o segnalazione di una risposta.

  Valori ammessi: "general", "response"

• message string · obbligatorio

  Commento fornito esplicitamente dall’utente.

  Da 5 a 4 000 caratteri

• email string · obbligatorio

  Indirizzo di contatto, oppure stringa vuota.

  Fino a 254 caratteri

• language string · obbligatorio

  Lingua di presentazione.

  Valori ammessi: "fr", "en", "it", "de", "es", "pt"

• source string · obbligatorio

  Punto di accesso da cui proviene il messaggio.

  Valori ammessi: "agent", "menu", "help", "response"

• version string · obbligatorio

  SHA dell’applicazione, oppure unknown.

  Formato tecnico

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

• screen string · obbligatorio

  Schermata da cui viene inviato il messaggio.

  Valori ammessi: "home", "clarification", "result", "other"

• response null | ReportedResponse · obbligatorio

  Risposta esatta allegata alla segnalazione, altrimenti null.

  Campi

  null

  null

  Risposta allegata ReportedResponse

  • kind string · obbligatorio

    Tipo di risposta allegata alla segnalazione.

    Valori ammessi: "clarification", "recommendation"

  • text string · obbligatorio

    Testo esatto della risposta allegata.

    Da 1 a 12 000 caratteri

  • reference string · obbligatorio

    Riferimento della risposta interessata.

    Formato tecnico

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

Risposta

200 application/json

{
  "ok": true
}

• ok boolean · obbligatorio

  Conferma la registrazione del messaggio.

  Valore: true

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