# API, MCP et agents

Documentation développeurs

Un agent peut soumettre un choix, recevoir une question de clarification, puis obtenir une recommandation et ses raisons. Aucun compte ni clé fournisseur à configurer.

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

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

Pour les assistants et clients MCP. Configure le serveur, puis découvre ses outils.

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

Pour ton application ou ton script. HTTP, authentification Bearer et réponses JSON.

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

Pour un agent dans la page ouverte. Identité et historique du navigateur.

## Connexion MCP

Adresse MCP

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

Transport HTTP distant, sans OAuth. Le jeton applicatif est passé aux outils, pas dans la configuration du serveur. Prévois 110 secondes pour un appel de décision.

Choisis ton client. Fusionne l’exemple avec ta configuration existante, sans la remplacer. Recharge ensuite les outils MCP et vérifie la présence de start_session, get_usage et decide.

**Claude Code**

Terminal · Bash

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

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

**Codex**

Fichier de configuration

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

Configuration · TOML

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

[Documentation du client ↗](https://developers.openai.com/codex/mcp/)

**Cursor**

Fichier de configuration

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

Configuration · JSON

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

[Documentation du client ↗](https://cursor.com/docs/mcp)

**OpenCode**

Fichier de configuration

```
opencode.json
```

Configuration · JSON

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

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

**Hermes Agent**

Terminal · Bash

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

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

**Mistral Vibe**

Fichier de configuration

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

Configuration · 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 = {}
```

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

**OpenClaw**

Fichier de configuration

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

Configuration · JSON

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

[Documentation du client ↗](https://docs.openclaw.ai/tools/mcp)

**Pi**

Fichier de configuration

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

Configuration · JSON

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

[Documentation du client ↗](https://pi.dev/docs/latest/mcp)

## Référence MCP

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

Écriture

Créer ou renouveler l’identité privée du client.

- `session` `string | null` facultatif · Par défaut null

Réponse: `Session`

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

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

Exemple illustratif · 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`

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Lecture

Consulter les crédits, leur renouvellement et l’état éventuel du cas.

- `session` `string` obligatoire
- `case_id` `string | null` facultatif · Par défaut null

Réponse: `Usage`

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

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

Exemple illustratif · 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.

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Calcul IA

Soumettre un tour de décision : question, recommandation ou erreur.

- `session` `string` obligatoire
- `case_id` `string` obligatoire
- `text` `string` obligatoire
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facultatif · Par défaut "fr"
- `refinements` `string[] | null` facultatif · Par défaut null
- `force_decision` `boolean` facultatif · Par défaut false
- `clarification_count` `integer` facultatif · Par défaut 0
- `clarification_version` `2` facultatif · Par défaut 2

Réponse: `DecisionResponse`

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

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

REST · Requête · Exemple illustratif · 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`

MCP · decide · Requête · JSON

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

**Question de clarification `Clarification`**

Une question à transmettre, ou une notice selon purpose. insufficient_evidence indique que les éléments ne permettent pas un classement défendable ; ne pas relancer sans information nouvelle de l’utilisateur.

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"clarification"`

- `question` `string` · obligatoire

Question à transmettre à l’utilisateur avant de continuer.

- `choices` `string[]` · obligatoire

Réponses proposées, si la question en fournit.

6 éléments maximum

- `format` `string` · obligatoire

Mode de réponse attendu par la question.

Valeurs possibles : `"single"`, `"multiple"`, `"text"`, `"number"`

- `unit` `string | null`

Unité d’une réponse numérique, ou null.

- `summary` `string` · obligatoire

Synthèse du dilemme.

- `purpose` `string`

Rôle de la question ou de la notice de périmètre.

Valeurs possibles : `"decision_scope"`, `"scope_notice"`, `"insufficient_evidence"`

- `metrics` `object`

Mesures techniques du traitement.

**Recommandation `Result`**

La recommandation, ses options, raisons et sources. Les poids sont des préférences relatives, pas des probabilités de réussite. result_id peut être absent.

Exemple illustratif · 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` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"result"`

- `summary` `string` · obligatoire

Synthèse du dilemme.

- `context` `string`

Contexte retenu pour la recommandation.

- `assumptions` `string[]`

Hypothèses retenues pour comparer les options.

- `criteria` `string[]`

Critères utilisés pour comparer les options.

- `options` `object[]` · obligatoire

Options comparées et informations associées.

De 2 à 8 éléments

- `selected` `string` · obligatoire

Identifiant de l’option recommandée.

- `sources` `object[]` · obligatoire

Sources renvoyées avec la recommandation.

- `caution` `string | null`

Précaution particulière, ou null.

- `timings` `object`

Durées des étapes du traitement.

- `models` `object`

Informations sur les modèles de ce tour.

- `metrics` `object`

Mesures techniques du traitement.

- `result_id` `string`

Identifiant du résultat appartenant à ce client.

**Erreur `Error`**

Un refus ou échec de pipeline. Vérifier type même après un HTTP 200 ; en MCP, isError signale également l’erreur.

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Lecture

Produire une carte du résultat déjà reçu, sans calcul IA ni stockage de l’image.

- `session` `string` obligatoire
- `result` `CardResult` obligatoire
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facultatif · Par défaut "fr"
- `theme` `"light" | "dark"` facultatif · Par défaut "light"

Réponse: `image/png`

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

#### Entrée

##### En-têtes

- `Authorization` `string` · obligatoire

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

##### Corps `application/json`

REST · Requête · Exemple illustratif · 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.

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Lecture

Lire le vote du client propriétaire de ce résultat.

- `session` `string` obligatoire
- `result_id` `string` obligatoire

Réponse: `Feedback`

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

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

Exemple illustratif · 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"`

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Écriture

Enregistrer l’avis explicite de l’utilisateur, sans déduire sa satisfaction.

- `session` `string` obligatoire
- `result_id` `string` obligatoire
- `helpful` `boolean` obligatoire
- `reason` `"misunderstood" | "missing_constraint" | "too_many_questions" | "too_vague" | null` facultatif · Par défaut null

Réponse: `Feedback`

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

#### Entrée

##### En-têtes

- `Authorization` `string` · obligatoire

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

##### Corps `application/json`

REST · Requête · Exemple illustratif · 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`

Exemple illustratif · 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"`

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

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

Écriture

Transmettre un message ou un signalement expressément autorisé.

- `session` `string` obligatoire
- `request_id` `string` obligatoire
- `message` `string` obligatoire
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` facultatif · Par défaut "fr"
- `kind` `"general" | "response"` facultatif · Par défaut "general"
- `email` `string` facultatif · Par défaut ""
- `response` `object | null` facultatif · Par défaut null

Réponse: `FeedbackAck`

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

#### Entrée

##### En-têtes

- `Authorization` `string` · obligatoire

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

##### Corps `application/json`

REST · Requête · Exemple illustratif · 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`

Exemple illustratif · JSON

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

- `ok` `boolean` · obligatoire

Confirme l’enregistrement du message.

Valeur : `true`

**Erreurs et reprise**

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

Exemple illustratif · JSON

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

- `type` `string` · obligatoire

Nature de la réponse renvoyée.

Valeur : `"error"`

- `code` `string` · obligatoire

Code à examiner pour traiter le refus ou l’échec.

- `message` `string`

Explication lisible du refus ou de l’échec.

- `retryable` `boolean`

Indique si une nouvelle tentative peut être envisagée.

- `resets_at` `string`

Date et heure du prochain renouvellement des crédits.

Date et heure au format ISO 8601

## Démarrage rapide

Avec curl et Python 3. Crée une identité une seule fois, conserve son jeton dans un stockage privé et restaure-le lors des visites suivantes.

Crée une session et conserve la valeur session. Utilise-la dans Authorization: Bearer *** pour les appels suivants. Elle est valable 90 jours ; renouvelle-la avec le même appel et ce jeton.

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

Choisis un Case-ID pour ton dilemme et conserve-le à chaque échange. Tu reçois une question ou une recommandation. Pour répondre, ajoute la question et ta réponse à refinements, puis augmente clarification_count de 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}'
```

## Session et authentification

Sans jeton, start_session crée une identité. Avec session, il renouvelle la même identité pour 90 jours. Un jeton invalide ou expiré est refusé, sans remplacement silencieux. REST et MCP partagent ce jeton ; ils ne lisent pas les cookies du navigateur.

Un Case-ID unique par dilemme, conservé jusqu’au résultat : 1 à 80 caractères parmi a-z, A-Z, 0-9, _ et -. Il identifie le cas, mais ne rend pas un calcul idempotent.

## Cycle d’un dilemme

1. Soumettre le choix avec son texte initial et un nouveau Case-ID.
2. Sur clarification, lire purpose : insufficient_evidence est une notice à présenter, sans question ni classement à inventer. Sinon, poser la question et attendre la vraie réponse ; ajouter question + réponse à refinements et augmenter clarification_count.
3. Sur result, conserver le JSON : le cas est terminé. Pour un nouveau calcul, utiliser un nouveau Case-ID.
4. Sur error, lire code et retryable. Ne pas rejouer automatiquement un calcul dont l’issue est ambiguë.

L’agent te transmet les questions et attend tes réponses, sans inventer les informations manquantes. Tu peux lui demander une recommandation sans autre question.

## Paramètres de décision

- `text` obligatoire

Le choix initial, conservé à chaque tour.

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

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

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

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

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

Nombre de réponses aux clarifications.

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

Version du contrat, toujours 2.

`2`
- `force_decision` facultatif

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

`boolean`

Texte + précisions : 24 000 caractères au total. Corps HTTP : 300 000 octets, reçus en 10 secondes ; une enveloppe fournisseur trop volumineuse peut aussi être refusée avant consommation.

## Réponses

### Question de clarification `type: clarification`

Une question à transmettre, ou une notice selon purpose. insufficient_evidence indique que les éléments ne permettent pas un classement défendable ; ne pas relancer sans information nouvelle de l’utilisateur.

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

### Recommandation `type: result`

La recommandation, ses options, raisons et sources. Les poids sont des préférences relatives, pas des probabilités de réussite. result_id peut être absent.

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

### Erreur `type: error`

Un refus ou échec de pipeline. Vérifier type même après un HTTP 200 ; en MCP, isError signale également l’erreur.

`type, code, message, retryable, resets_at`

Exemple illustratif · clarification · JSON

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

## Résultats et retours

### Exporter le résultat en PNG

Fournis le résultat reçu dans result, avec language et theme (light ou dark). PNG privé, nom dans Content-Disposition, Cache-Control: no-store. Aucun crédit de dilemme consommé, aucune publication. En MCP : image native et métadonnées de fichier.

Requête · Exemple illustratif · 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
```

### Lire ou enregistrer un avis

result_id identifie un résultat de cette identité. helpful est un booléen ; reason est facultatif pour un avis négatif uniquement : misunderstood, missing_constraint, too_many_questions ou too_vague. Un résultat absent, expiré ou étranger renvoie le même 404.

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

Requête · Exemple illustratif · 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
```

### Envoyer un message ou signaler une réponse

request_id : 32 caractères hexadécimaux minuscules. message : 5 caractères hors espaces minimum, 4 000 maximum. kind=general pour un message ; kind=response pour un signalement avec la réponse exacte jointe. E-mail facultatif. Garde le même identifiant et contenu ; pas de rejeu automatique après une panne ambiguë.

Requête · Exemple illustratif · 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
```

## Crédits

Un crédit couvre un dilemme jusqu’à sa première recommandation, clarifications comprises. Tout nouveau calcul après cette recommandation utilise un autre crédit.

Consulte get_usage en MCP ou GET /api/v1/usage en REST pour connaître tes crédits restants et leur renouvellement.

Les plafonds viennent de la politique active, pas d’une valeur figée dans ce guide. L’export PNG et les retours ne consomment pas de crédit de dilemme ; ils gardent leurs limites techniques et anti-abus.

## Erreurs et reprise

[`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 : session absente, invalide ou expirée, origine refusée ou cookies interdits. 408/413/422 : délai, taille ou entrée invalide. 409 : cas terminé. 429 : quota, budget ou capacité. 503 : service indisponible. Vérifie aussi le champ type de la réponse : un échec de pipeline peut arriver après admission. Ne rejoue pas automatiquement un calcul après une panne ambiguë ; le Case-ID n’est pas une clé d’idempotence du calcul.

Une déconnexion peut laisser du travail déjà consommé. Lire les quotas ne permet pas de reconstituer une réponse perdue.

## Agent dans le navigateur

Dans un navigateur compatible, WebMCP permet à ton agent d’utiliser la page ouverte, avec ton historique et tes crédits. Sinon, utilise la connexion MCP distante ou l’API. L’accès distant fonctionne à l’écrit ; la dictée reste disponible dans l’application.

Commence par get_dilemma. submit_dilemma transmet un choix ou une réponse ; recommend_dilemma demande une recommandation sans autre question. Les actions de résultat utilisent le cas visible, pas le jeton distant.

WebMCP ajoute l’export local avec aperçu, les avis et les signalements, ainsi que list_saved_dilemmas et get_saved_dilemma pour lire l’historique de ce navigateur. L’URL de l’image expire à la fermeture de l’aperçu. Ni cet historique ni les cookies du navigateur ne sont partagés avec le MCP distant.

## Référence technique

Les schémas OpenAPI décrivent les corps et réponses complets. Le guide Markdown sert de point d’entrée aux agents ; le catalogue et la Server Card exposent la découverte 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)

Les échanges textuels sont conservés 30 jours par le service. L’historique du navigateur reste sur ton appareil et n’est pas partagé avec l’agent distant.

[Confidentialité et fournisseurs](https://dilem.si/fr/privacy/)

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

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