# API, MCP y agentes

Documentación para desarrolladores

Un agente puede enviar una elección, recibir una pregunta aclaratoria y obtener una recomendación razonada. No necesita cuenta ni claves de proveedores.

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

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

Para asistentes y clientes MCP. Configura el servidor y descubre sus herramientas.

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

Para tu aplicación o script. HTTP, autenticación Bearer y respuestas JSON.

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

Para un agente en la página abierta. Usa identidad e historial del navegador.

## Conexión MCP

Dirección MCP

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

Transporte HTTP remoto, sin OAuth. El token de aplicación se pasa a las herramientas, no a la configuración del servidor. Prevé 110 segundos para una decisión.

Elige tu cliente. Integra el ejemplo en tu configuración existente sin reemplazarla. Recarga las herramientas MCP y comprueba que start_session, get_usage y decide estén disponibles.

**Claude Code**

Terminal · Bash

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

[Documentación del cliente ↗](https://code.claude.com/docs/en/mcp)

**Codex**

Archivo de configuración

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

Configuración · TOML

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

[Documentación del cliente ↗](https://developers.openai.com/codex/mcp/)

**Cursor**

Archivo de configuración

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

Configuración · JSON

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

[Documentación del cliente ↗](https://cursor.com/docs/mcp)

**OpenCode**

Archivo de configuración

```
opencode.json
```

Configuración · JSON

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

[Documentación del cliente ↗](https://opencode.ai/docs/mcp-servers/)

**Hermes Agent**

Terminal · Bash

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

[Documentación del cliente ↗](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

**Mistral Vibe**

Archivo de configuración

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

Configuración · 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 = {}
```

[Documentación del cliente ↗](https://docs.mistral.ai/vibe/code/cli/mcp-servers)

**OpenClaw**

Archivo de configuración

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

Configuración · JSON

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

[Documentación del cliente ↗](https://docs.openclaw.ai/tools/mcp)

**Pi**

Archivo de configuración

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

Configuración · JSON

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

[Documentación del cliente ↗](https://pi.dev/docs/latest/mcp)

## Referencia MCP

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

Escritura

Crear o renovar la identidad privada del cliente.

- `session` `string | null` opcional · Por defecto null

Respuesta: `Session`

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

#### Entrada

##### Cabeceras

- `Authorization` `string`

Token de sesión enviado como Bearer <session>.

No se requiere cuerpo de solicitud.

#### Respuesta

##### 200 `application/json`

Ejemplo ilustrativo · JSON

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

- `session` `string` · obligatorio

Token privado del cliente que se conserva para las llamadas siguientes.

- `expires_in` `integer` · obligatorio

Duración de la sesión en segundos.

Valor: `7776000`

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Lectura

Leer créditos, renovación y estado opcional del caso.

- `session` `string` obligatorio
- `case_id` `string | null` opcional · Por defecto null

Respuesta: `Usage`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

- `X-Dilem-Case-ID` `string`

Conserva este identificador en todos los turnos del mismo dilema.

**Formato técnico**

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

No se requiere cuerpo de solicitud.

#### Respuesta

##### 200 `application/json`

Ejemplo ilustrativo · 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` · obligatorio

Día UTC de los contadores.

Fecha ISO 8601

- `resets_at` `string` · obligatorio

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

- `collective` `object` · obligatorio

Contador colectivo de dilemas completados.

**Campos**

- `completed` `integer` · obligatorio

Número de dilemas completados en el contador colectivo.

- `dilemmas` `object` · obligatorio

Créditos de dilemas usados, disponibles y permitidos.

**Campos**

- `used` `integer` · obligatorio

Créditos ya utilizados.

Mínimo: 0

- `limit` `integer` · obligatorio

Límite de créditos de la política activa.

Mínimo: 0

- `remaining` `integer` · obligatorio

Créditos todavía disponibles.

Mínimo: 0

- `case` `object` · obligatorio

Estado del dilema identificado por el Case-ID enviado.

**Campos**

- `id` `string | null` · obligatorio

Case-ID solicitado, o null si no se proporcionó.

- `admitted` `boolean` · obligatorio

Indica si el dilema ya fue admitido en la cuota.

- `completed` `boolean` · obligatorio

Indica si una primera recomendación completó el dilema.

- `voice` `object` · obligatorio

Duraciones y límites de dictado en segundos.

**Campos**

- `seconds_used` `number`

Segundos de dictado ya consumidos.

- `seconds_reserved` `number`

Segundos reservados temporalmente por una captura en curso.

- `seconds_remaining` `number`

Segundos de dictado todavía disponibles.

- `seconds_limit` `number`

Límite total de dictado en segundos.

- `max_seconds` `number`

Duración máxima de una captura en segundos.

- `budget` `object` · obligatorio

Presupuesto financiero compartido y disponibilidad del servicio.

**Campos**

- `daily_usd` `number` · obligatorio

Límite financiero diario del servicio en dólares estadounidenses.

- `available` `boolean` · obligatorio

Indica si el presupuesto aún permite cálculos.

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Cálculo IA

Enviar un turno: pregunta, recomendación o error.

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

Respuesta: `DecisionResponse`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

- `X-Dilem-Case-ID` `string` · obligatorio

Conserva este identificador en todos los turnos del mismo dilema.

**Formato técnico**

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

##### Cuerpo `application/json`

REST · Solicitud · Ejemplo ilustrativo · JSON

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

- `text` `string` · obligatorio

Elección inicial conservada en cada turno.

De 1 a 6 000 caracteres

- `language` `string` · obligatorio

Idioma de la interfaz. Las respuestas siguen las palabras del usuario.

Valores permitidos: `"fr"`, `"en"`, `"it"`, `"de"`, `"es"`, `"pt"`

- `refinements` `string[]`

Preguntas y respuestas reales, en orden cronológico.

40 elementos como máximo · 6 000 caracteres como máximo por elemento · Por defecto: `[]`

- `force_decision` `boolean`

Solo cuando el usuario pide recomendar sin más preguntas.

Por defecto: `false`

- `clarification_count` `integer`

Número de respuestas a aclaraciones.

De 0 a 20 · Por defecto: `0`

- `clarification_version` `integer`

Versión del contrato, siempre 2.

Por defecto: `2` · Valor: `2`

MCP · decide · Solicitud · JSON

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

#### Respuesta

##### 200 `application/json`

**Pregunta de aclaración `Clarification`**

Una pregunta o un aviso según purpose. insufficient_evidence indica que no hay base suficiente para una clasificación defendible; no reintentes sin nueva información del usuario.

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"clarification"`

- `question` `string` · obligatorio

Pregunta que transmitir al usuario antes de continuar.

- `choices` `string[]` · obligatorio

Respuestas propuestas, si la pregunta las incluye.

6 elementos como máximo

- `format` `string` · obligatorio

Formato de respuesta esperado por la pregunta.

Valores permitidos: `"single"`, `"multiple"`, `"text"`, `"number"`

- `unit` `string | null`

Unidad de una respuesta numérica, o null.

- `summary` `string` · obligatorio

Resumen del dilema.

- `purpose` `string`

Propósito de la pregunta o aviso de alcance.

Valores permitidos: `"decision_scope"`, `"scope_notice"`, `"insufficient_evidence"`

- `metrics` `object`

Métricas técnicas del procesamiento.

**Recomendación `Result`**

Recomendación, opciones, motivos y fuentes. Los pesos son preferencias relativas, no probabilidades de éxito. result_id puede faltar.

Ejemplo ilustrativo · 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` · obligatorio

Tipo de respuesta devuelta.

Valor: `"result"`

- `summary` `string` · obligatorio

Resumen del dilema.

- `context` `string`

Contexto utilizado para la recomendación.

- `assumptions` `string[]`

Supuestos utilizados para comparar las opciones.

- `criteria` `string[]`

Criterios utilizados para comparar las opciones.

- `options` `object[]` · obligatorio

Opciones comparadas e información asociada.

De 2 a 8 elementos

- `selected` `string` · obligatorio

Identificador de la opción recomendada.

- `sources` `object[]` · obligatorio

Fuentes devueltas con la recomendación.

- `caution` `string | null`

Advertencia específica, o null.

- `timings` `object`

Duraciones de las etapas del procesamiento.

- `models` `object`

Información sobre los modelos de este turno.

- `metrics` `object`

Métricas técnicas del procesamiento.

- `result_id` `string`

Identificador del resultado perteneciente a este cliente.

**Error `Error`**

Rechazo o error de la ejecución. Revisa type incluso tras HTTP 200; MCP también indica isError.

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Lectura

Crear una tarjeta del resultado recibido, sin IA ni almacenamiento de imagen.

- `session` `string` obligatorio
- `result` `CardResult` obligatorio
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` opcional · Por defecto "fr"
- `theme` `"light" | "dark"` opcional · Por defecto "light"

Respuesta: `image/png`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

##### Cuerpo `application/json`

REST · Solicitud · Ejemplo ilustrativo · 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` · obligatorio

Resultado ya recibido que se envía para generar el PNG.

**Campos**

- `summary` `string` · obligatorio

Resumen del dilema.

De 1 a 6 000 caracteres

- `selected` `string` · obligatorio

Identificador de la opción recomendada.

32 caracteres como máximo

- `options` `CardOption[]` · obligatorio

Opciones comparadas e información asociada.

De 2 a 8 elementos

**Campos**

- `id` `string` · obligatorio

Identificador único de esta opción en el resultado.

**Formato técnico**

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

- `label` `string` · obligatorio

Etiqueta de la opción en la tarjeta.

De 1 a 120 caracteres

- `description` `string`

Descripción breve mostrada con la opción.

240 caracteres como máximo · Por defecto: `""`

- `probability` `number` · obligatorio

Peso de preferencia, no probabilidad de éxito.

De 0 a 1

- `language` `string`

Idioma de presentación.

Valores permitidos: `"fr"`, `"en"`, `"it"`, `"de"`, `"es"`, `"pt"` · Por defecto: `"fr"`

- `theme` `string`

Tema visual de la tarjeta PNG.

Valores permitidos: `"light"`, `"dark"` · Por defecto: `"light"`

#### Respuesta

##### 200 `image/png`

Archivo PNG privado adjunto. El nombre se devuelve en Content-Disposition.

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Lectura

Leer el voto del cliente propietario.

- `session` `string` obligatorio
- `result_id` `string` obligatorio

Respuesta: `Feedback`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

##### Parámetros de ruta

- `result_id` `string` · obligatorio

Identificador del resultado perteneciente a este cliente.

**Formato técnico**

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

No se requiere cuerpo de solicitud.

#### Respuesta

##### 200 `application/json`

Ejemplo ilustrativo · JSON

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

- `result_id` `string` · obligatorio

Identificador del resultado perteneciente a este cliente.

**Formato técnico**

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

- `helpful` `boolean | null` · obligatorio

Valoración registrada, o null si no se ha votado.

- `reason` `null | string` · obligatorio

Motivo de la valoración negativa, o null.

Valores permitidos: `null`, `"misunderstood"`, `"missing_constraint"`, `"too_many_questions"`, `"too_vague"`

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Escritura

Registrar el voto explícito del usuario, sin deducir su satisfacción.

- `session` `string` obligatorio
- `result_id` `string` obligatorio
- `helpful` `boolean` obligatorio
- `reason` `"misunderstood" | "missing_constraint" | "too_many_questions" | "too_vague" | null` opcional · Por defecto null

Respuesta: `Feedback`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

##### Cuerpo `application/json`

REST · Solicitud · Ejemplo ilustrativo · JSON

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

- `result_id` `string` · obligatorio

Identificador del resultado perteneciente a este cliente.

**Formato técnico**

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

- `helpful` `boolean` · obligatorio

Valoración explícita del usuario sobre la respuesta.

- `reason` `null | string`

Motivo de la valoración negativa, o null.

Valores permitidos: `null`, `"misunderstood"`, `"missing_constraint"`, `"too_many_questions"`, `"too_vague"`

#### Respuesta

##### 200 `application/json`

Ejemplo ilustrativo · JSON

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

- `result_id` `string` · obligatorio

Identificador del resultado perteneciente a este cliente.

**Formato técnico**

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

- `helpful` `boolean | null` · obligatorio

Valoración registrada, o null si no se ha votado.

- `reason` `null | string` · obligatorio

Motivo de la valoración negativa, o null.

Valores permitidos: `null`, `"misunderstood"`, `"missing_constraint"`, `"too_many_questions"`, `"too_vague"`

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

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

Escritura

Enviar un mensaje o informe expresamente autorizado.

- `session` `string` obligatorio
- `request_id` `string` obligatorio
- `message` `string` obligatorio
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` opcional · Por defecto "fr"
- `kind` `"general" | "response"` opcional · Por defecto "general"
- `email` `string` opcional · Por defecto ""
- `response` `object | null` opcional · Por defecto null

Respuesta: `FeedbackAck`

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

#### Entrada

##### Cabeceras

- `Authorization` `string` · obligatorio

Token de sesión enviado como Bearer <session>.

##### Cuerpo `application/json`

REST · Solicitud · Ejemplo ilustrativo · 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` · obligatorio

Identificador que se conserva para deduplicar el mismo envío.

**Formato técnico**

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

- `kind` `string` · obligatorio

Mensaje libre o aviso sobre una respuesta.

Valores permitidos: `"general"`, `"response"`

- `message` `string` · obligatorio

Comentario proporcionado expresamente por el usuario.

De 5 a 4 000 caracteres

- `email` `string` · obligatorio

Dirección de contacto, o cadena vacía.

254 caracteres como máximo

- `language` `string` · obligatorio

Idioma de presentación.

Valores permitidos: `"fr"`, `"en"`, `"it"`, `"de"`, `"es"`, `"pt"`

- `source` `string` · obligatorio

Punto de acceso desde el que se originó el mensaje.

Valores permitidos: `"agent"`, `"menu"`, `"help"`, `"response"`

- `version` `string` · obligatorio

SHA de la aplicación, o unknown.

**Formato técnico**

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

- `screen` `string` · obligatorio

Pantalla desde la que se envía el mensaje.

Valores permitidos: `"home"`, `"clarification"`, `"result"`, `"other"`

- `response` `null | ReportedResponse` · obligatorio

Respuesta exacta adjunta al aviso, o null.

**Campos**

**`null`**

`null`

**Respuesta adjunta `ReportedResponse`**

- `kind` `string` · obligatorio

Tipo de respuesta adjunta al aviso.

Valores permitidos: `"clarification"`, `"recommendation"`

- `text` `string` · obligatorio

Texto exacto de la respuesta adjunta.

De 1 a 12 000 caracteres

- `reference` `string` · obligatorio

Referencia de la respuesta correspondiente.

**Formato técnico**

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

#### Respuesta

##### 200 `application/json`

Ejemplo ilustrativo · JSON

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

- `ok` `boolean` · obligatorio

Confirma que se registró el mensaje.

Valor: `true`

**Errores y recuperación**

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

Ejemplo ilustrativo · JSON

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

- `type` `string` · obligatorio

Tipo de respuesta devuelta.

Valor: `"error"`

- `code` `string` · obligatorio

Código que consultar para gestionar el rechazo o fallo.

- `message` `string`

Explicación legible del rechazo o fallo.

- `retryable` `boolean`

Indica si se puede considerar otro intento.

- `resets_at` `string`

Fecha y hora de la próxima renovación de créditos.

Fecha y hora ISO 8601

## Inicio rápido

Requiere curl y Python 3. Crea la identidad una vez, guarda el token en privado y recupéralo en visitas posteriores.

Crea una sesión y conserva el valor session. Úsalo como Authorization: Bearer *** en las siguientes llamadas. Dura 90 días; renuévalo con la misma llamada y el mismo 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'
```

Elige un Case-ID para tu dilema y mantenlo durante la conversación. Recibirás una pregunta o una recomendación. Para responder, añade la pregunta y tu respuesta a refinements e incrementa clarification_count en 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}'
```

## Sesión y autenticación

Sin token, start_session crea una identidad. Con session renueva la misma identidad por 90 días. Un token inválido o caducado se rechaza, nunca se sustituye en silencio. REST y MCP comparten el token; no leen las cookies del navegador.

Un Case-ID único por dilema hasta el resultado: de 1 a 80 caracteres entre a-z, A-Z, 0-9, _ y -. Identifica el caso, pero no hace idempotente el cálculo.

## Ciclo de un dilema

1. Envía la elección inicial con un nuevo Case-ID.
2. Con clarification, revisa purpose: insufficient_evidence es un aviso que mostrar, no una pregunta ni una invitación a inventar una clasificación. En otro caso, pregunta y espera la respuesta real; añade pregunta + respuesta a refinements e incrementa clarification_count.
3. Con result, conserva el JSON: el caso ha terminado. Usa otro Case-ID para un nuevo cálculo.
4. Con error, revisa code y retryable. No repitas automáticamente un cálculo de resultado ambiguo.

El agente te transmite las preguntas y espera tus respuestas, sin inventar información que falte. Puedes pedirle una recomendación sin más preguntas.

## Parámetros de decisión

- `text` obligatorio

Elección inicial conservada en cada turno.

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

Idioma de la interfaz. Las respuestas siguen las palabras del usuario.

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

Preguntas y respuestas reales, en orden cronológico.

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

Número de respuestas a aclaraciones.

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

Versión del contrato, siempre 2.

`2`
- `force_decision` opcional

Solo cuando el usuario pide recomendar sin más preguntas.

`boolean`

Texto + precisiones: 24 000 caracteres en total. Cuerpo HTTP: 300 000 bytes en 10 segundos; una carga del proveedor demasiado grande puede rechazarse antes del consumo.

## Respuestas

### Pregunta de aclaración `type: clarification`

Una pregunta o un aviso según purpose. insufficient_evidence indica que no hay base suficiente para una clasificación defendible; no reintentes sin nueva información del usuario.

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

### Recomendación `type: result`

Recomendación, opciones, motivos y fuentes. Los pesos son preferencias relativas, no probabilidades de éxito. result_id puede faltar.

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

### Error `type: error`

Rechazo o error de la ejecución. Revisa type incluso tras HTTP 200; MCP también indica isError.

`type, code, message, retryable, resets_at`

Ejemplo ilustrativo · clarification · JSON

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

## Resultados y comentarios

### Exportar el resultado como PNG

Pasa el resultado recibido en result, con language y theme (light o dark). PNG privado, nombre en Content-Disposition, Cache-Control: no-store. Sin crédito ni publicación. MCP devuelve una imagen nativa y metadatos del archivo.

Solicitud · Ejemplo ilustrativo · 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
```

### Leer o registrar un voto

result_id pertenece a esta identidad. helpful es booleano; reason es opcional solo para un voto negativo: misunderstood, missing_constraint, too_many_questions o too_vague. Resultados ausentes, caducados o ajenos devuelven el mismo 404.

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

Solicitud · Ejemplo ilustrativo · 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
```

### Enviar un mensaje o informar de una respuesta

request_id: 32 caracteres hexadecimales en minúscula. message: al menos 5 caracteres sin espacios, máximo 4 000. kind=general para mensajes; kind=response para informes con la respuesta exacta adjunta. Correo opcional. Conserva ID y contenido; sin repetición automática tras un fallo ambiguo.

Solicitud · Ejemplo ilustrativo · 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éditos

Un crédito cubre el dilema hasta su primera recomendación, incluidas las aclaraciones. Cualquier cálculo posterior a esa recomendación usa otro crédito.

Usa get_usage por MCP o GET /api/v1/usage por REST para consultar los créditos restantes y cuándo se renuevan.

Los límites vienen de la política activa, no de valores fijos en esta guía. PNG y comentarios no consumen créditos de dilema, pero mantienen límites técnicos y antiabuso.

## Errores y recuperación

[`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: sesión ausente, inválida o caducada, origen rechazado o cookies prohibidas. 408/413/422: tiempo, tamaño o entrada inválida. 409: caso terminado. 429: cuota, presupuesto o capacidad. 503: servicio no disponible. Comprueba también type: la ejecución puede fallar tras la admisión. No repitas automáticamente un cálculo tras un fallo ambiguo; Case-ID no es una clave de idempotencia.

Una desconexión puede dejar trabajo consumido. Consultar el uso no reconstruye una respuesta perdida.

## Agentes en el navegador

En un navegador compatible, WebMCP permite al agente usar la página abierta con tu historial y tus créditos. Si no, usa MCP remoto o la API. El acceso remoto admite texto; el dictado sigue disponible en la aplicación.

Lee primero get_dilemma. submit_dilemma envía una elección o respuesta; recommend_dilemma pide recomendar sin otra pregunta. Las acciones usan el caso visible, no el token remoto.

WebMCP añade exportación local con vista previa, votos y avisos, además de list_saved_dilemmas y get_saved_dilemma para el historial de este navegador. La URL de imagen caduca al cerrar la vista previa. El historial y las cookies no se comparten con MCP remoto.

## Referencia técnica

Los esquemas OpenAPI describen solicitudes y respuestas completas. La guía Markdown sirve de entrada a los agentes; catálogo y Server Card permiten descubrir 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)

El servicio conserva los intercambios de texto durante 30 días. El historial del navegador permanece en tu dispositivo y no se comparte con el agente remoto.

[Privacidad y proveedores](https://dilem.si/es/privacy/)

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

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