API, MCP y agentes

Entrada

Cabeceras

• Authorization string

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

No se requiere cuerpo de solicitud.

Respuesta

200 application/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

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

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

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

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

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

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

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

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

{
  "type": "result",
  "summary": "Train or bus for my commute?",
  "options": [
    {
      "id": "train",
      "label": "Take the train",
      "description": "Use the direct rail connection.",
      "probability": 0.7
    },
    {
      "id": "bus",
      "label": "Take the bus",
      "description": "Use the bus stop near home.",
      "probability": 0.3
    }
  ],
  "selected": "train",
  "sources": [],
  "result_id": "0123456789abcdef0123456789abcdef"
}

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

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

Entrada

Cabeceras

• Authorization string · obligatorio

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

Cuerpo application/json

{
  "result": {
    "summary": "Train or bus for my commute?",
    "selected": "train",
    "options": [
      {
        "id": "train",
        "label": "Take the train",
        "description": "Use the direct rail connection.",
        "probability": 0.7
      },
      {
        "id": "bus",
        "label": "Take the bus",
        "description": "Use the bus stop near home.",
        "probability": 0.3
      }
    ]
  },
  "language": "en",
  "theme": "light"
}

• result CardResult · 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.

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

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

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

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

Entrada

Cabeceras

• Authorization string · obligatorio

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

Cuerpo application/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

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

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

Entrada

Cabeceras

• Authorization string · obligatorio

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

Cuerpo application/json

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "kind": "general",
  "message": "Please explain how the recommendation uses my constraints.",
  "email": "",
  "language": "en",
  "source": "agent",
  "version": "unknown",
  "screen": "other",
  "response": null
}

• request_id string · 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

{
  "ok": true
}

• ok boolean · obligatorio

  Confirma que se registró el mensaje.

  Valor: true

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