API, MCP e agentes

Entrada

Cabeçalhos

• Authorization string

  Token de sessão enviado como Bearer <session>.

Não é necessário corpo do pedido.

Resposta

200 application/json

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

• session string · obrigatório

  Token privado do cliente, a conservar para chamadas posteriores.

• expires_in integer · obrigatório

  Prazo de validade da sessão, em segundos.

  Valor: 7776000

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

Entrada

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

• X-Dilem-Case-ID string

  Mantém este identificador em todas as interações do mesmo dilema.

  Formato técnico

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

Não é necessário corpo do pedido.

Resposta

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 · obrigatório

  Dia UTC dos contadores.

  Data ISO 8601

• resets_at string · obrigatório

  Data e hora da próxima renovação dos créditos.

  Data e hora ISO 8601

• collective object · obrigatório

  Contador coletivo de dilemas concluídos.

  Campos

  • completed integer · obrigatório

    Número de dilemas concluídos no contador coletivo.

• dilemmas object · obrigatório

  Créditos de dilemas usados, disponíveis e permitidos.

  Campos

  • used integer · obrigatório

    Créditos já utilizados.

    Mínimo: 0

  • limit integer · obrigatório

    Limite de créditos da política ativa.

    Mínimo: 0

  • remaining integer · obrigatório

    Créditos ainda disponíveis.

    Mínimo: 0

• case object · obrigatório

  Estado do dilema identificado pelo Case-ID enviado.

  Campos

  • id string | null · obrigatório

    Case-ID solicitado, ou null se não foi fornecido.

  • admitted boolean · obrigatório

    Indica se o dilema já foi admitido na quota.

  • completed boolean · obrigatório

    Indica se uma primeira recomendação concluiu o dilema.

• voice object · obrigatório

  Durações e limites do ditado, em segundos.

  Campos

  • seconds_used number

    Segundos de ditado já consumidos.

  • seconds_reserved number

    Segundos temporariamente reservados por uma captura em curso.

  • seconds_remaining number

    Segundos de ditado ainda disponíveis.

  • seconds_limit number

    Limite total de ditado, em segundos.

  • max_seconds number

    Duração máxima de uma captura, em segundos.

• budget object · obrigatório

  Orçamento financeiro partilhado e disponibilidade do serviço.

  Campos

  • daily_usd number · obrigatório

    Limite financeiro diário do serviço, em dólares dos EUA.

  • available boolean · obrigatório

    Indica se o orçamento ainda permite cálculos.

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

Entrada

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

• X-Dilem-Case-ID string · obrigatório

  Mantém este identificador em todas as interações do mesmo dilema.

  Formato técnico

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

Corpo application/json

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

• text string · obrigatório

  Escolha inicial mantida em cada turno.

  De 1 a 6 000 caracteres

• language string · obrigatório

  Idioma da interface. As respostas seguem as palavras do utilizador.

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

• refinements string[]

  Perguntas e respostas reais, por ordem cronológica.

  Até 40 elementos · Até 6 000 caracteres por elemento · Predefinição: []

• force_decision boolean

  Apenas quando o utilizador pede uma recomendação sem mais perguntas.

  Predefinição: false

• clarification_count integer

  Número de respostas a esclarecimentos.

  De 0 a 20 · Predefinição: 0

• clarification_version integer

  Versão do contrato, sempre 2.

  Predefinição: 2 · Valor: 2

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

Resposta

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

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

Corpo application/json

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

• result CardResult · obrigatório

  Resultado já recebido a fornecer para gerar o PNG.

  Campos

  • summary string · obrigatório

    Síntese do dilema.

    De 1 a 6 000 caracteres

  • selected string · obrigatório

    Identificador da opção recomendada.

    Até 32 caracteres

  • options CardOption[] · obrigatório

    Opções comparadas e informações associadas.

    De 2 a 8 elementos

    Campos

    • id string · obrigatório

      Identificador único desta opção no resultado.

      Formato técnico

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

    • label string · obrigatório

      Designação da opção no cartão.

      De 1 a 120 caracteres

    • description string

      Descrição breve apresentada com a opção.

      Até 240 caracteres · Predefinição: ""

    • probability number · obrigatório

      Peso de preferência, não probabilidade de sucesso.

      De 0 a 1

• language string

  Idioma de apresentação.

  Valores permitidos: "fr", "en", "it", "de", "es", "pt" · Predefinição: "fr"

• theme string

  Tema visual do cartão PNG.

  Valores permitidos: "light", "dark" · Predefinição: "light"

Resposta

200 image/png

Ficheiro PNG privado em anexo. O nome é devolvido em Content-Disposition.

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

Entrada

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

Parâmetros do caminho

• result_id string · obrigatório

  Identificador do resultado pertencente a este cliente.

  Formato técnico

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

Não é necessário corpo do pedido.

Resposta

200 application/json

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

• result_id string · obrigatório

  Identificador do resultado pertencente a este cliente.

  Formato técnico

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

• helpful boolean | null · obrigatório

  Avaliação registada, ou null se não houve voto.

• reason null | string · obrigatório

  Motivo da avaliação negativa, ou null.

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

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

Entrada

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

Corpo application/json

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

• result_id string · obrigatório

  Identificador do resultado pertencente a este cliente.

  Formato técnico

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

• helpful boolean · obrigatório

  Avaliação explícita do utilizador sobre a resposta.

• reason null | string

  Motivo da avaliação negativa, ou null.

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

Resposta

200 application/json

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

• result_id string · obrigatório

  Identificador do resultado pertencente a este cliente.

  Formato técnico

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

• helpful boolean | null · obrigatório

  Avaliação registada, ou null se não houve voto.

• reason null | string · obrigatório

  Motivo da avaliação negativa, ou null.

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

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

Entrada

Cabeçalhos

• Authorization string · obrigatório

  Token de sessão enviado como Bearer <session>.

Corpo application/json

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

• request_id string · obrigatório

  Identificador a conservar para evitar envios duplicados.

  Formato técnico

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

• kind string · obrigatório

  Mensagem livre ou denúncia de uma resposta.

  Valores permitidos: "general", "response"

• message string · obrigatório

  Comentário fornecido expressamente pelo utilizador.

  De 5 a 4 000 caracteres

• email string · obrigatório

  Endereço de contacto, ou cadeia vazia.

  Até 254 caracteres

• language string · obrigatório

  Idioma de apresentação.

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

• source string · obrigatório

  Ponto de entrada de origem da mensagem.

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

• version string · obrigatório

  SHA da aplicação, ou unknown.

  Formato técnico

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

• screen string · obrigatório

  Ecrã a partir do qual a mensagem é enviada.

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

• response null | ReportedResponse · obrigatório

  Resposta exata anexada à denúncia, caso contrário null.

  Campos

  null

  null

  Resposta anexada ReportedResponse

  • kind string · obrigatório

    Tipo de resposta anexada à denúncia.

    Valores permitidos: "clarification", "recommendation"

  • text string · obrigatório

    Texto exato da resposta anexada.

    De 1 a 12 000 caracteres

  • reference string · obrigatório

    Referência da resposta em causa.

    Formato técnico

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

Resposta

200 application/json

{
  "ok": true
}

• ok boolean · obrigatório

  Confirma o registo da mensagem.

  Valor: true

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