# API, MCP e agentes

Documentação para programadores

Um agente pode enviar uma escolha, receber uma pergunta de esclarecimento e obter uma recomendação fundamentada. Não exige conta nem chaves dos fornecedores.

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

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

Para assistentes e clientes MCP. Configura o servidor e descobre as ferramentas.

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

Para a tua aplicação ou script. HTTP, autenticação Bearer e respostas JSON.

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

Para um agente na página aberta. Usa identidade e histórico do navegador.

## Ligação MCP

Endereço MCP

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

Transporte HTTP remoto, sem OAuth. O token da aplicação é passado às ferramentas, não à configuração do servidor. Prevê 110 segundos para uma decisão.

Escolhe o teu cliente. Junta o exemplo à configuração existente sem a substituir. Recarrega as ferramentas MCP e verifica se start_session, get_usage e decide estão disponíveis.

**Claude Code**

Terminal · Bash

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

[Documentação do cliente ↗](https://code.claude.com/docs/en/mcp)

**Codex**

Ficheiro de configuração

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

Configuração · TOML

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

[Documentação do cliente ↗](https://developers.openai.com/codex/mcp/)

**Cursor**

Ficheiro de configuração

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

Configuração · JSON

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

[Documentação do cliente ↗](https://cursor.com/docs/mcp)

**OpenCode**

Ficheiro de configuração

```
opencode.json
```

Configuração · JSON

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

[Documentação do cliente ↗](https://opencode.ai/docs/mcp-servers/)

**Hermes Agent**

Terminal · Bash

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

[Documentação do cliente ↗](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

**Mistral Vibe**

Ficheiro de configuração

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

Configuração · 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 = {}
```

[Documentação do cliente ↗](https://docs.mistral.ai/vibe/code/cli/mcp-servers)

**OpenClaw**

Ficheiro de configuração

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

Configuração · JSON

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

[Documentação do cliente ↗](https://docs.openclaw.ai/tools/mcp)

**Pi**

Ficheiro de configuração

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

Configuração · JSON

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

[Documentação do cliente ↗](https://pi.dev/docs/latest/mcp)

## Referência MCP

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

Escrita

Criar ou renovar a identidade privada do cliente.

- `session` `string | null` opcional · Predefinição null

Resposta: `Session`

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

#### Entrada

##### Cabeçalhos

- `Authorization` `string`

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

Não é necessário corpo do pedido.

#### Resposta

##### 200 `application/json`

Exemplo ilustrativo · 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`

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Leitura

Ler créditos, renovação e estado opcional do caso.

- `session` `string` obrigatório
- `case_id` `string | null` opcional · Predefinição null

Resposta: `Usage`

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

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

Exemplo 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` · 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.

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Cálculo IA

Enviar um turno: pergunta, recomendação ou erro.

- `session` `string` obrigatório
- `case_id` `string` obrigatório
- `text` `string` obrigatório
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` opcional · Predefinição "fr"
- `refinements` `string[] | null` opcional · Predefinição null
- `force_decision` `boolean` opcional · Predefinição false
- `clarification_count` `integer` opcional · Predefinição 0
- `clarification_version` `2` opcional · Predefinição 2

Resposta: `DecisionResponse`

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

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

REST · Pedido · Exemplo ilustrativo · 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`

MCP · decide · Pedido · JSON

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

**Pergunta de esclarecimento `Clarification`**

Uma pergunta ou um aviso segundo purpose. insufficient_evidence indica que não há base para uma classificação fundamentada; não repitas sem informação nova do utilizador.

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"clarification"`

- `question` `string` · obrigatório

Pergunta a transmitir ao utilizador antes de continuar.

- `choices` `string[]` · obrigatório

Respostas propostas, quando incluídas na pergunta.

Até 6 elementos

- `format` `string` · obrigatório

Formato de resposta esperado pela pergunta.

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

- `unit` `string | null`

Unidade de uma resposta numérica, ou null.

- `summary` `string` · obrigatório

Síntese do dilema.

- `purpose` `string`

Finalidade da pergunta ou do aviso de âmbito.

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

- `metrics` `object`

Métricas técnicas do processamento.

**Recomendação `Result`**

Recomendação, opções, razões e fontes. Os pesos são preferências relativas, não probabilidades de sucesso. result_id pode estar ausente.

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

Tipo de resposta devolvida.

Valor: `"result"`

- `summary` `string` · obrigatório

Síntese do dilema.

- `context` `string`

Contexto utilizado para a recomendação.

- `assumptions` `string[]`

Pressupostos utilizados para comparar as opções.

- `criteria` `string[]`

Critérios utilizados para comparar as opções.

- `options` `object[]` · obrigatório

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

De 2 a 8 elementos

- `selected` `string` · obrigatório

Identificador da opção recomendada.

- `sources` `object[]` · obrigatório

Fontes devolvidas com a recomendação.

- `caution` `string | null`

Precaução específica, ou null.

- `timings` `object`

Durações das etapas do processamento.

- `models` `object`

Informações sobre os modelos desta interação.

- `metrics` `object`

Métricas técnicas do processamento.

- `result_id` `string`

Identificador do resultado pertencente a este cliente.

**Erro `Error`**

Recusa ou erro da execução. Verifica type mesmo após HTTP 200; MCP também indica isError.

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Leitura

Criar um cartão do resultado recebido, sem IA nem armazenamento de imagem.

- `session` `string` obrigatório
- `result` `CardResult` obrigatório
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` opcional · Predefinição "fr"
- `theme` `"light" | "dark"` opcional · Predefinição "light"

Resposta: `image/png`

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

#### Entrada

##### Cabeçalhos

- `Authorization` `string` · obrigatório

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

##### Corpo `application/json`

REST · Pedido · Exemplo 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` · 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.

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Leitura

Ler o voto do cliente proprietário.

- `session` `string` obrigatório
- `result_id` `string` obrigatório

Resposta: `Feedback`

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

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

Exemplo ilustrativo · 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"`

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Escrita

Registar o voto explícito do utilizador, sem deduzir satisfação.

- `session` `string` obrigatório
- `result_id` `string` obrigatório
- `helpful` `boolean` obrigatório
- `reason` `"misunderstood" | "missing_constraint" | "too_many_questions" | "too_vague" | null` opcional · Predefinição null

Resposta: `Feedback`

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

#### Entrada

##### Cabeçalhos

- `Authorization` `string` · obrigatório

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

##### Corpo `application/json`

REST · Pedido · Exemplo ilustrativo · 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`

Exemplo ilustrativo · 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"`

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

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

Escrita

Enviar uma mensagem ou denúncia expressamente autorizada.

- `session` `string` obrigatório
- `request_id` `string` obrigatório
- `message` `string` obrigatório
- `language` `"fr" | "en" | "it" | "de" | "es" | "pt"` opcional · Predefinição "fr"
- `kind` `"general" | "response"` opcional · Predefinição "general"
- `email` `string` opcional · Predefinição ""
- `response` `object | null` opcional · Predefinição null

Resposta: `FeedbackAck`

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

#### Entrada

##### Cabeçalhos

- `Authorization` `string` · obrigatório

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

##### Corpo `application/json`

REST · Pedido · Exemplo 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` · 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`

Exemplo ilustrativo · JSON

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

- `ok` `boolean` · obrigatório

Confirma o registo da mensagem.

Valor: `true`

**Erros e recuperação**

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

Exemplo ilustrativo · JSON

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

- `type` `string` · obrigatório

Tipo de resposta devolvida.

Valor: `"error"`

- `code` `string` · obrigatório

Código a consultar para tratar a recusa ou falha.

- `message` `string`

Explicação legível da recusa ou falha.

- `retryable` `boolean`

Indica se pode ser considerada outra tentativa.

- `resets_at` `string`

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

Data e hora ISO 8601

## Início rápido

Requer curl e Python 3. Cria a identidade uma vez, guarda o token em privado e recupera-o nas visitas seguintes.

Cria uma sessão e guarda o valor session. Usa-o em Authorization: Bearer *** nas chamadas seguintes. É válido durante 90 dias; renova-o com a mesma chamada e o mesmo 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'
```

Escolhe um Case-ID para o teu dilema e mantém-no ao longo da conversa. Recebes uma pergunta ou uma recomendação. Para responder, acrescenta a pergunta e a tua resposta a refinements e aumenta clarification_count em 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}'
```

## Sessão e autenticação

Sem token, start_session cria uma identidade. Com session renova a mesma identidade por 90 dias. Um token inválido ou expirado é recusado, nunca substituído silenciosamente. REST e MCP partilham o token; não leem cookies do navegador.

Um Case-ID único por dilema até ao resultado: de 1 a 80 caracteres entre a-z, A-Z, 0-9, _ e -. Identifica o caso, mas não torna o cálculo idempotente.

## Ciclo de um dilema

1. Envia a escolha inicial com um novo Case-ID.
2. Com clarification, lê purpose: insufficient_evidence é um aviso a apresentar, não uma pergunta nem um convite a inventar uma classificação. Caso contrário, faz a pergunta e espera a resposta real; acrescenta pergunta + resposta a refinements e incrementa clarification_count.
3. Com result, conserva o JSON: o caso terminou. Usa outro Case-ID para um novo cálculo.
4. Com error, lê code e retryable. Não repitas automaticamente um cálculo de resultado ambíguo.

O agente transmite-te as perguntas e espera pelas tuas respostas, sem inventar a informação em falta. Podes pedir-lhe uma recomendação sem mais perguntas.

## Parâmetros de decisão

- `text` obrigatório

Escolha inicial mantida em cada turno.

`string · 1–6000`
- `language` obrigatório

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

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

Perguntas e respostas reais, por ordem cronológica.

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

Número de respostas a esclarecimentos.

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

Versão do contrato, sempre 2.

`2`
- `force_decision` opcional

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

`boolean`

Texto + precisões: 24 000 caracteres no total. Corpo HTTP: 300 000 bytes em 10 segundos; uma carga do fornecedor demasiado grande pode ser recusada antes do consumo.

## Respostas

### Pergunta de esclarecimento `type: clarification`

Uma pergunta ou um aviso segundo purpose. insufficient_evidence indica que não há base para uma classificação fundamentada; não repitas sem informação nova do utilizador.

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

### Recomendação `type: result`

Recomendação, opções, razões e fontes. Os pesos são preferências relativas, não probabilidades de sucesso. result_id pode estar ausente.

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

### Erro `type: error`

Recusa ou erro da execução. Verifica type mesmo após HTTP 200; MCP também indica isError.

`type, code, message, retryable, resets_at`

Exemplo ilustrativo · clarification · JSON

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

## Resultados e comentários

### Exportar o resultado como PNG

Passa o resultado recebido em result, com language e theme (light ou dark). PNG privado, nome em Content-Disposition, Cache-Control: no-store. Sem crédito nem publicação. MCP devolve uma imagem nativa e metadados do ficheiro.

Pedido · Exemplo 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
```

### Ler ou registar um voto

result_id pertence a esta identidade. helpful é booleano; reason é opcional apenas para um voto negativo: misunderstood, missing_constraint, too_many_questions ou too_vague. Resultados ausentes, expirados ou alheios devolvem o mesmo 404.

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

Pedido · Exemplo 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 uma mensagem ou denunciar uma resposta

request_id: 32 caracteres hexadecimais minúsculos. message: pelo menos 5 caracteres sem espaços, máximo 4 000. kind=general para mensagens; kind=response para denúncias com a resposta exata anexa. Email facultativo. Mantém ID e conteúdo; sem repetição automática após falha ambígua.

Pedido · Exemplo 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

Um crédito cobre o dilema até à primeira recomendação, incluindo esclarecimentos. Qualquer novo cálculo após essa recomendação usa outro crédito.

Usa get_usage por MCP ou GET /api/v1/usage por REST para consultar os créditos restantes e a sua renovação.

Os limites vêm da política ativa, não de valores fixos neste guia. PNG e comentários não consomem créditos de dilema, mas mantêm limites técnicos e antiabuso.

## Erros e recuperação

[`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: sessão ausente, inválida ou expirada, origem recusada ou cookies proibidos. 408/413/422: tempo, tamanho ou entrada inválida. 409: caso concluído. 429: quota, orçamento ou capacidade. 503: serviço indisponível. Verifica também type: a execução pode falhar após a admissão. Não repitas automaticamente um cálculo após uma falha ambígua; Case-ID não é uma chave de idempotência.

Uma desconexão pode deixar trabalho consumido. A leitura do uso não reconstrói uma resposta perdida.

## Agentes no navegador

Num navegador compatível, o WebMCP permite ao agente usar a página aberta com o teu histórico e os teus créditos. Caso contrário, usa MCP remoto ou a API. O acesso remoto aceita texto; o ditado continua disponível na aplicação.

Lê primeiro get_dilemma. submit_dilemma envia uma escolha ou resposta; recommend_dilemma pede uma recomendação sem mais perguntas. As ações usam o caso visível, não o token remoto.

WebMCP acrescenta exportação local com pré-visualização, votos e denúncias, além de list_saved_dilemmas e get_saved_dilemma para o histórico deste navegador. O URL da imagem expira ao fechar a pré-visualização. Histórico e cookies não são partilhados com MCP remoto.

## Referência técnica

Os esquemas OpenAPI descrevem pedidos e respostas completos. O guia Markdown é o ponto de entrada para agentes; catálogo e Server Card expõem a descoberta 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)

O serviço conserva as conversas de texto durante 30 dias. O histórico do navegador fica no teu dispositivo e não é partilhado com o agente remoto.

[Privacidade e fornecedores](https://dilem.si/pt/privacy/)

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

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