API atual/Referência completa/Dashboards

POSTGerar card por texto (IA)

Descreve em linguagem natural o que você quer ver e recebe a especificação de um card, com um preview dos dados.

Em vez de montar a especificação à mão, você escreve algo como "pedidos por status em uma rosca, últimos 90 dias" e a plataforma devolve uma especificação válida. A rota não grava nada: ela só gera e mostra um preview. Para salvar, envie a spec devolvida para Criar card. A conversa pode ser refinada mandando as mensagens anteriores em history.

POST/api/v1/admin/dashboards/ai/specAdmin

Gerar a especificação de um card a partir de texto

Corpo da requisição

promptstringobrigatório

O que você quer ver, em linguagem natural.

historyarray

Turnos anteriores da conversa, para refinar: cada item tem role e content.

rolestring

Quem falou: user ou assistant.

contentstring

Texto da mensagem.

allow_sqlbooleanpadrão: false

Permite que o resultado seja um card kind: sql. Só vale para quem tem manage_reports; para os demais é ignorado.

periodobject

Período usado no preview quando o card gerado tem período inherit.

modestringobrigatório

inheritpresetfixedrelative

Como o período é definido.

presetstring

todayyesterdaylast7last30last90thisMonthlastMonththisQuarterthisYearlastYear

Obrigatório com mode=preset.

fromstring

Com mode=fixed: primeiro dia, YYYY-MM-DD.

tostring

Com mode=fixed: último dia, YYYY-MM-DD.

last_n_daysinteger

Com mode=relative: quantos dias para trás, até 1095.

fieldstring

Campo de data da entidade a usar como referência (entidade.campo). Padrão: o campo de data principal da entidade.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/dashboards/ai/spec" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "pedidos por status em uma rosca, últimos 90 dias", "period": {"mode": "preset", "preset": "last30"}}'

Resposta

200Especificação gerada

json

{
  "spec": {
    "spec_version": 1,
    "kind": "query",
    "title": "Pedidos por status",
    "viz": { "type": "donut", "snippet_id": "pedidos-por-status" },
    "query": {
      "entity": "orders",
      "period": { "mode": "preset", "preset": "last90" },
      "metrics": [ { "id": "pedidos", "kind": "agg", "agg": "count", "field": "orders.id" } ],
      "dimensions": [ { "id": "status", "field": "orders.status" } ]
    }
  },
  "explanation_pt": "Rosca com a contagem de pedidos por status nos últimos 90 dias.",
  "warnings": [],
  "served_by": "provider-1",
  "preview": { "columns": [], "rows": [], "meta": { "row_count": 0, "truncated": false, "limit": 100, "elapsed_ms": 4, "cached": false } }
}

Campos da resposta

specobject

A especificação gerada, pronta para Criar card.

explanation_ptstring

Explicação curta do que foi montado, sempre em português.

warningsarray

Avisos de texto sobre o resultado, por exemplo "o filtro zerou o resultado".

served_bystring

Identificador de quem gerou a resposta. Informativo.

previewobject

Dados do card no formato dataset de Preview. Ausente se a especificação gerada não pôde ser executada.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
400	Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.	`{"error":"invalid request body","detail":"json: unknown field \"foo\""}`
403	Pediu SQL (`allow_sql`) e o gerador respondeu com SQL, mas o usuário não tem `manage_reports`.	`{"error":"ai_sql_not_allowed","detail":"..."}`
422	Não foi possível gerar uma especificação válida para o pedido.	`{"error":"ai_generation_failed","detail":"..."}`
503	Nenhum provedor de IA disponível. Use o construtor manual.	`{"error":"ai_unavailable","detail":"nenhum provider de IA respondeu \u2014 tente novamente em instantes ou use o construtor manual"}`

Veja também