# API, MCP e agenti

Documentazione per sviluppatori

Un agente può inviare una scelta, ricevere una domanda di chiarimento e ottenere una raccomandazione motivata. Non servono account né chiavi dei fornitori.

REST v1.1.0 MCP · Streamable HTTP [Markdown ↗](https://dilem.si/it/docs/index.md)

## [MCP ↗](https://dilem.si/it/docs/#connect)

Per assistenti e client MCP. Configura il server, poi scopri i suoi strumenti.

## [REST API ↗](https://dilem.si/it/docs/#quickstart)

Per la tua app o uno script. HTTP, autenticazione Bearer e risposte JSON.

## [WebMCP ↗](https://dilem.si/it/docs/#browser)

Per un agente nella pagina aperta. Usa identità e cronologia del browser.

## Connessione MCP

Indirizzo MCP

```
https://dilem.si/api/v1/mcp
```

Trasporto HTTP remoto, senza OAuth. Il token applicativo va passato agli strumenti, non alla configurazione del server. Prevedi 110 secondi per una decisione.

Scegli il tuo client. Integra l’esempio nella configurazione esistente senza sostituirla. Ricarica gli strumenti MCP e verifica che start_session, get_usage e decide siano disponibili.

**Claude Code**

Terminal · Bash

```
claude mcp add --transport http dilem https://dilem.si/api/v1/mcp
```

[Documentazione del client ↗](https://code.claude.com/docs/en/mcp)

**Codex**

File di configurazione

```
~/.codex/config.toml
```

Configurazione · TOML

```
[mcp_servers.dilem]
url = "https://dilem.si/api/v1/mcp"
tool_timeout_sec = 110
```

[Documentazione del client ↗](https://developers.openai.com/codex/mcp/)

**Cursor**

File di configurazione

```
.cursor/mcp.json
```

Configurazione · JSON

```
{
  "mcpServers": {
    "dilem": {
      "url": "https://dilem.si/api/v1/mcp"
    }
  }
}
```

[Documentazione del client ↗](https://cursor.com/docs/mcp)

**OpenCode**

File di configurazione

```
opencode.json
```

Configurazione · JSON

```
{
  "mcp": {
    "dilem": {
      "type": "remote",
      "url": "https://dilem.si/api/v1/mcp",
      "enabled": true,
      "oauth": false
    }
  }
}
```

[Documentazione del client ↗](https://opencode.ai/docs/mcp-servers/)

**Hermes Agent**

Terminal · Bash

```
hermes mcp add dilem --url https://dilem.si/api/v1/mcp
```

[Documentazione del client ↗](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

**Mistral Vibe**

File di configurazione

```
~/.vibe/config.toml
```

Configurazione · TOML

```
[[mcp_servers]]
name = "dilem"
transport = "streamable-http"
url = "https://dilem.si/api/v1/mcp"
tool_timeout_sec = 110

[mcp_servers.auth]
type = "static"
headers = {}
```

[Documentazione del client ↗](https://docs.mistral.ai/vibe/code/cli/mcp-servers)

**OpenClaw**

File di configurazione

```
~/.openclaw/openclaw.json
```

Configurazione · JSON

```
{
  "mcp": {
    "servers": {
      "dilem": {
        "url": "https://dilem.si/api/v1/mcp",
        "transport": "streamable-http",
        "enabled": true,
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 110000
      }
    }
  }
}
```

[Documentazione del client ↗](https://docs.openclaw.ai/tools/mcp)

**Pi**

File di configurazione

```
~/.pi/agent/mcp.json
```

Configurazione · JSON

```
{
  "mcpServers": {
    "dilem": {
      "url": "https://dilem.si/api/v1/mcp",
      "timeout": 110
    }
  }
}
```

[Documentazione del client ↗](https://pi.dev/docs/latest/mcp)

## Riferimento MCP

### [start_session](https://dilem.si/it/docs/#tool-start_session)

Scrittura

Creare o rinnovare l’identità privata del client.

- `session` `string | null` facoltativo · Predefinito null

Risposta: `Session`

**POST `/api/v1/session`**

#### Input

##### Intestazioni

- `Authorization` `string`

Token di sessione inviato come Bearer <session>.

Nessun corpo della richiesta richiesto.

#### Risposta

##### 200 `application/json`

Esempio illustrativo · 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`

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [get_usage](https://dilem.si/it/docs/#tool-get_usage)

Lettura

Leggere crediti, rinnovo e stato del caso.

- `session` `string` obbligatorio
- `case_id` `string | null` facoltativo · Predefinito null

Risposta: `Usage`

**GET `/api/v1/usage`**

#### 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`

Esempio illustrativo · 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.

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [decide](https://dilem.si/it/docs/#tool-decide)

Calcolo IA

Inviare un turno: domanda, raccomandazione o errore.

- `session` `string` obbligatorio
- `case_id` `string` obbligatorio
- `text` `string` obbligatorio
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facoltativo · Predefinito "fr"
- `refinements` `string[] | null` facoltativo · Predefinito null
- `force_decision` `boolean` facoltativo · Predefinito false
- `clarification_count` `integer` facoltativo · Predefinito 0
- `clarification_version` `2` facoltativo · Predefinito 2

Risposta: `DecisionResponse`

**POST `/api/v1/decide`**

#### 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`

REST · Richiesta · Esempio illustrativo · 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`

MCP · decide · Richiesta · JSON

```
{
  "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`

**Domanda di chiarimento `Clarification`**

Una domanda da trasmettere o un avviso secondo purpose. insufficient_evidence indica che mancano elementi per una classifica fondata; non riprovare senza nuove informazioni dell’utente.

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"clarification"`

- `question` `string` · obbligatorio

Domanda da trasmettere all’utente prima di continuare.

- `choices` `string[]` · obbligatorio

Risposte proposte, se previste dalla domanda.

Fino a 6 elementi

- `format` `string` · obbligatorio

Formato di risposta previsto dalla domanda.

Valori ammessi: `"single"`, `"multiple"`, `"text"`, `"number"`

- `unit` `string | null`

Unità di una risposta numerica, oppure null.

- `summary` `string` · obbligatorio

Sintesi del dilemma.

- `purpose` `string`

Scopo della domanda o dell’avviso sul perimetro.

Valori ammessi: `"decision_scope"`, `"scope_notice"`, `"insufficient_evidence"`

- `metrics` `object`

Metriche tecniche dell’elaborazione.

**Raccomandazione `Result`**

Raccomandazione, opzioni, motivi e fonti. I pesi sono preferenze relative, non probabilità di successo. result_id può mancare.

Esempio illustrativo · JSON

```
{
  "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` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"result"`

- `summary` `string` · obbligatorio

Sintesi del dilemma.

- `context` `string`

Contesto usato per la raccomandazione.

- `assumptions` `string[]`

Ipotesi usate per confrontare le opzioni.

- `criteria` `string[]`

Criteri usati per confrontare le opzioni.

- `options` `object[]` · obbligatorio

Opzioni confrontate e informazioni associate.

Da 2 a 8 elementi

- `selected` `string` · obbligatorio

Identificativo dell’opzione raccomandata.

- `sources` `object[]` · obbligatorio

Fonti restituite con la raccomandazione.

- `caution` `string | null`

Avvertenza specifica, oppure null.

- `timings` `object`

Durate delle fasi di elaborazione.

- `models` `object`

Informazioni sui modelli di questo turno.

- `metrics` `object`

Metriche tecniche dell’elaborazione.

- `result_id` `string`

Identificativo del risultato appartenente a questo client.

**Errore `Error`**

Rifiuto o errore della pipeline. Controlla type anche dopo HTTP 200; MCP segnala anche isError.

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [export_result_card](https://dilem.si/it/docs/#tool-export_result_card)

Lettura

Creare una carta dal risultato ricevuto, senza IA né archivio immagini.

- `session` `string` obbligatorio
- `result` `CardResult` obbligatorio
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facoltativo · Predefinito "fr"
- `theme` `"light" | "dark"` facoltativo · Predefinito "light"

Risposta: `image/png`

**POST `/api/v1/result-card`**

#### Input

##### Intestazioni

- `Authorization` `string` · obbligatorio

Token di sessione inviato come Bearer <session>.

##### Corpo `application/json`

REST · Richiesta · Esempio illustrativo · 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.

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 · 415 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [get_result_feedback](https://dilem.si/it/docs/#tool-get_result_feedback)

Lettura

Leggere il voto del client proprietario.

- `session` `string` obbligatorio
- `result_id` `string` obbligatorio

Risposta: `Feedback`

**GET `/api/v1/feedback/{result_id}`**

#### 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`

Esempio illustrativo · 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"`

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 · 404 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [set_result_feedback](https://dilem.si/it/docs/#tool-set_result_feedback)

Scrittura

Registrare il voto esplicito dell’utente, senza dedurne la soddisfazione.

- `session` `string` obbligatorio
- `result_id` `string` obbligatorio
- `helpful` `boolean` obbligatorio
- `reason` `"misunderstood" | "missing_constraint" | "too_many_questions" | "too_vague" | null` facoltativo · Predefinito null

Risposta: `Feedback`

**POST `/api/v1/feedback`**

#### Input

##### Intestazioni

- `Authorization` `string` · obbligatorio

Token di sessione inviato come Bearer <session>.

##### Corpo `application/json`

REST · Richiesta · Esempio illustrativo · 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`

Esempio illustrativo · 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"`

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 · 415 · 404 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

### [send_user_feedback](https://dilem.si/it/docs/#tool-send_user_feedback)

Scrittura

Inviare un messaggio o una segnalazione autorizzata.

- `session` `string` obbligatorio
- `request_id` `string` obbligatorio
- `message` `string` obbligatorio
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facoltativo · Predefinito "fr"
- `kind` `"general" | "response"` facoltativo · Predefinito "general"
- `email` `string` facoltativo · Predefinito ""
- `response` `object | null` facoltativo · Predefinito null

Risposta: `FeedbackAck`

**POST `/api/v1/user-feedback`**

#### Input

##### Intestazioni

- `Authorization` `string` · obbligatorio

Token di sessione inviato come Bearer <session>.

##### Corpo `application/json`

REST · Richiesta · Esempio illustrativo · 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`

Esempio illustrativo · JSON

```
{
  "ok": true
}
```

- `ok` `boolean` · obbligatorio

Conferma la registrazione del messaggio.

Valore: `true`

**Errori e ripresa**

403 · 408 · 409 · 413 · 422 · 429 · 503 · 415 `application/json`

Esempio illustrativo · JSON

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

- `type` `string` · obbligatorio

Tipo di risposta restituita.

Valore: `"error"`

- `code` `string` · obbligatorio

Codice da leggere per gestire un rifiuto o un errore.

- `message` `string`

Spiegazione leggibile del rifiuto o dell’errore.

- `retryable` `boolean`

Indica se è possibile valutare un nuovo tentativo.

- `resets_at` `string`

Data e ora del prossimo rinnovo dei crediti.

Data e ora ISO 8601

## Avvio rapido

Richiede curl e Python 3. Crea l’identità una sola volta, conserva il token in privato e riutilizzalo nelle visite successive.

Crea una sessione e conserva il valore session. Usalo in Authorization: Bearer *** nelle chiamate successive. Vale 90 giorni; rinnovalo con la stessa chiamata e lo stesso token.

POST /api/v1/session · Bash

```
DILEM_SESSION=$(curl --fail-with-body --silent --show-error --max-time 15 \
  https://dilem.si/api/v1/session \
  -H 'Content-Type: application/json' -d '{}' | \
  python3 -c 'import json, sys; print(json.load(sys.stdin)["session"])')
```

GET /api/v1/usage · Bash

```
curl --fail-with-body --max-time 15 https://dilem.si/api/v1/usage \
  -H "Authorization: Bearer ${DILEM_SESSION:?}" \
  -H 'X-Dilem-Case-ID: my-unique-dilemma-id'
```

Scegli un Case-ID per il dilemma e mantienilo durante la conversazione. Ricevi una domanda o una raccomandazione. Per rispondere, aggiungi domanda e risposta a refinements e aumenta clarification_count di 1.

POST /api/v1/decide · Bash

```
curl --fail-with-body --max-time 110 --output result.json https://dilem.si/api/v1/decide \
  -H "Authorization: Bearer ${DILEM_SESSION:?}" \
  -H 'X-Dilem-Case-ID: my-unique-dilemma-id' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Train or car for a weekend trip?","language":"en","refinements":[],"clarification_count":0,"clarification_version":2}'
```

## Sessione e autenticazione

Senza token, start_session crea un’identità. Con session rinnova la stessa identità per 90 giorni. Un token non valido o scaduto viene rifiutato, mai sostituito in silenzio. REST e MCP condividono il token; non leggono i cookie del browser.

Un Case-ID univoco per dilemma fino al risultato: da 1 a 80 caratteri tra a-z, A-Z, 0-9, _ e -. Identifica il caso, ma non rende il calcolo idempotente.

## Ciclo di un dilemma

1. Invia la scelta iniziale con un nuovo Case-ID.
2. Con clarification, leggi purpose: insufficient_evidence è un avviso da mostrare, non una domanda né un invito a inventare una classifica. Altrimenti poni la domanda e attendi la risposta reale; aggiungi domanda + risposta a refinements e aumenta clarification_count.
3. Con result, conserva il JSON: il caso è concluso. Usa un nuovo Case-ID per un altro calcolo.
4. Con error, leggi code e retryable. Non ripetere automaticamente un calcolo dall’esito ambiguo.

L’agente ti trasmette le domande e aspetta le tue risposte, senza inventare le informazioni mancanti. Puoi chiedergli una raccomandazione senza altre domande.

## Parametri della decisione

- `text` obbligatorio

Scelta iniziale, mantenuta a ogni turno.

`string · 1–6000`
- `language` obbligatorio

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

`fr | en | it | de | es | pt`
- `refinements` facoltativo

Domande e risposte reali in ordine cronologico.

`array · ≤40 × 6000`
- `clarification_count` facoltativo

Numero di risposte ai chiarimenti.

`integer · 0–20`
- `clarification_version` facoltativo

Versione del contratto, sempre 2.

`2`
- `force_decision` facoltativo

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

`boolean`

Testo + precisazioni: 24 000 caratteri totali. Corpo HTTP: 300 000 byte in 10 secondi; un payload del fornitore troppo grande può essere rifiutato prima del consumo.

## Risposte

### Domanda di chiarimento `type: clarification`

Una domanda da trasmettere o un avviso secondo purpose. insufficient_evidence indica che mancano elementi per una classifica fondata; non riprovare senza nuove informazioni dell’utente.

`type, question, choices, format, unit, summary, purpose, metrics`

### Raccomandazione `type: result`

Raccomandazione, opzioni, motivi e fonti. I pesi sono preferenze relative, non probabilità di successo. result_id può mancare.

`type, summary, context, assumptions, criteria, options, selected, sources, caution, timings, models, metrics, result_id`

### Errore `type: error`

Rifiuto o errore della pipeline. Controlla type anche dopo HTTP 200; MCP segnala anche isError.

`type, code, message, retryable, resets_at`

Esempio illustrativo · clarification · JSON

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

## Risultati e feedback

### Esportare il risultato in PNG

Passa il risultato ricevuto in result, con language e theme (light o dark). PNG privato, nome in Content-Disposition e Cache-Control: no-store. Nessun credito o pubblicazione. MCP restituisce un’immagine nativa e metadati del file.

Richiesta · Esempio illustrativo · Bash

```
python3 -c 'import json, sys; print(json.dumps({"result": json.load(sys.stdin), "language": "fr", "theme": "light"}))' < result.json > card-input.json
```

POST /api/v1/result-card · Bash

```
curl --fail-with-body --max-time 15 https://dilem.si/api/v1/result-card \
  -H "Authorization: Bearer ${DILEM_SESSION:?}" \
  -H "Content-Type: application/json" \
  --data-binary @card-input.json --output dilem.png
```

### Leggere o registrare un voto

result_id appartiene a questa identità. helpful è booleano; reason è facoltativo solo per un voto negativo: misunderstood, missing_constraint, too_many_questions o too_vague. Risultati assenti, scaduti o altrui danno lo stesso 404.

`GET /api/v1/feedback/{result_id}`

Richiesta · Esempio illustrativo · JSON

```
{"result_id": "<result_id from your result>", "helpful": false, "reason": "missing_constraint"}
```

POST /api/v1/feedback · Bash

```
curl --fail-with-body --max-time 15 https://dilem.si/api/v1/feedback \
  -H "Authorization: Bearer ${DILEM_SESSION:?}" \
  -H "Content-Type: application/json" \
  --data-binary @feedback-input.json
```

### Inviare un messaggio o segnalare una risposta

request_id: 32 caratteri esadecimali minuscoli. message: almeno 5 caratteri non bianchi, massimo 4 000. kind=general per un messaggio; kind=response per una segnalazione con risposta esatta allegata. Email facoltativa. Mantieni ID e contenuto; nessuna ripetizione automatica dopo un errore ambiguo.

Richiesta · Esempio illustrativo · JSON

```
{
  "request_id": "<32 lowercase hex characters>",
  "kind": "general",
  "message": "<user-authorized message>",
  "email": "",
  "language": "fr",
  "source": "agent",
  "version": "unknown",
  "screen": "other",
  "response": null
}
```

POST /api/v1/user-feedback · Bash

```
curl --fail-with-body --max-time 15 https://dilem.si/api/v1/user-feedback \
  -H "Authorization: Bearer ${DILEM_SESSION:?}" \
  -H "Content-Type: application/json" \
  --data-binary @user-feedback-input.json
```

## Crediti

Un credito copre il dilemma fino alla prima raccomandazione, chiarimenti compresi. Ogni nuovo calcolo successivo usa un altro credito.

Usa get_usage tramite MCP o GET /api/v1/usage tramite REST per conoscere i crediti rimasti e quando si rinnovano.

I limiti provengono dalla politica attiva, non da valori fissi in questa guida. Esportazione PNG e feedback non consumano crediti, ma mantengono limiti tecnici e antiabuso.

## Errori e ripresa

[`HTTP 403`](https://dilem.si/openapi.json)[`HTTP 408`](https://dilem.si/openapi.json)[`HTTP 409`](https://dilem.si/openapi.json)[`HTTP 413`](https://dilem.si/openapi.json)[`HTTP 422`](https://dilem.si/openapi.json)[`HTTP 429`](https://dilem.si/openapi.json)[`HTTP 503`](https://dilem.si/openapi.json)

403: sessione assente, non valida o scaduta, origine rifiutata o cookie vietati. 408/413/422: tempo, dimensione o dati non validi. 409: caso concluso. 429: quota, budget o capacità. 503: servizio indisponibile. Controlla anche type: la pipeline può fallire dopo l’ammissione. Non ripetere automaticamente un calcolo dopo un errore ambiguo; Case-ID non è una chiave di idempotenza.

Una disconnessione può lasciare lavoro già consumato. La lettura dei consumi non ricostruisce una risposta persa.

## Agenti nel browser

In un browser compatibile, WebMCP permette all’agente di usare la pagina aperta con la tua cronologia e i tuoi crediti. Altrimenti usa MCP remoto o l’API. L’accesso remoto accetta testo; la dettatura resta disponibile nell’app.

Leggi prima get_dilemma. submit_dilemma invia scelta o risposta; recommend_dilemma chiede una raccomandazione senza altre domande. Le azioni usano il caso visibile, non il token remoto.

WebMCP aggiunge esportazione locale con anteprima, voti e segnalazioni, oltre a list_saved_dilemmas e get_saved_dilemma per la cronologia di questo browser. L’URL dell’immagine scade alla chiusura dell’anteprima. Cronologia e cookie non vengono condivisi con MCP remoto.

## Riferimento tecnico

Gli schemi OpenAPI descrivono corpi e risposte completi. La guida Markdown è il punto d’ingresso per gli agenti; catalogo e Server Card espongono la scoperta MCP.

[OpenAPI 3.1](https://dilem.si/openapi.json)[AI Catalog](https://dilem.si/.well-known/ai-catalog.json)[MCP Server Card](https://dilem.si/mcp-server-card.json)[Agent guide · Markdown](https://dilem.si/agents.md)[llms.txt](https://dilem.si/llms.txt)

Il servizio conserva gli scambi testuali per 30 giorni. La cronologia del browser resta sul tuo dispositivo e non viene condivisa con l’agente remoto.

[Privacy e fornitori](https://dilem.si/it/privacy/)

[Contatto · contact@dilem.si](mailto:contact@dilem.si)

[HTML](https://dilem.si/it/docs/)